feat: productionize SLM harness UX

Author: piotrlaczkowski

AGENTS.md

@@ -12,7 +12,7 @@
 | Concept | Purpose |
 |---------|---------|
 | **Pipeline** | YAML-configurable execution graph of 16 phases |
-| **Agents** | 15 built-in role experts with SLM-optimized prompts |
+| **Agents** | 17 built-in role experts with SLM-optimized prompts |
 | **Blocks** | Marketplace-ready YAML packages: pipelines, agents, quality, packs |
 | **Stacks** | Provider/model presets (omlx-local, deepseek, openai, …) |
 | **Skills** | Claude Code–compatible `SKILL.md` convention packs |
@@ -292,7 +292,7 @@ Slots are user-inserted agent calls around phase anchors:
 
 ---
 
-## 5. Built-in Specialists (16 total)
+## 5. Built-in Specialists (17 total)
 
 Defined in `pkg/agents/prompts.go` + `pkg/agents/factory.go`:
 

Makefile

@@ -1,6 +1,6 @@
 MODULE := github.com/UnicoLab/slmcode
 BIN    := slmcode
-VERSION ?= 0.14.0
+VERSION ?= 0.15.0
 PREFIX ?= $(HOME)/.local
 GIT_COMMIT := $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
 BUILD_TIME := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)

README.md

@@ -13,7 +13,7 @@
 
 <p align="center">
   <a href="https://unicolab.ai"><img alt="UnicoLab" src="https://img.shields.io/badge/Made%20with%20%E2%99%A5%20by-UnicoLab-0f6e8c?style=flat-square" /></a>
-  <a href="https://github.com/UnicoLab/smlcode/releases/latest"><img alt="release" src="https://img.shields.io/github/v/release/UnicoLab/smlcode?style=flat-square&color=2dd4bf&label=v0.13.1" /></a>
+  <a href="https://github.com/UnicoLab/smlcode/releases/latest"><img alt="release" src="https://img.shields.io/github/v/release/UnicoLab/smlcode?style=flat-square&color=2dd4bf&label=v0.15.0" /></a>
   <a href="https://github.com/UnicoLab/smlcode/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/UnicoLab/smlcode/ci.yml?branch=main&style=flat-square&label=CI" /></a>
   <img alt="go" src="https://img.shields.io/badge/go-1.23+-00ADD8?style=flat-square&logo=go&logoColor=white" />
   <img alt="license" src="https://img.shields.io/badge/license-MIT-0ea5e9?style=flat-square" />
@@ -130,15 +130,15 @@ Deep dive: **[docs/PROVIDERS.md](docs/PROVIDERS.md)**
 | 💨 **Wave fast-path** | When ALL tasks have clean QA + disk evidence, skip reviewer LLM entirely |
 | 🏎️ **`fast_model`** | Dual-model routing — 8B for light agents (reviewer, planner), 30B for heavy (worker, tester) |
 
-### 🧩 Agents (19 specialists)
+### 🧩 Agents (17 specialists)
 
 | Agent | Role | Tools |
 |-------|------|-------|
 | 🧭 `explorer` | Codebase deep-dive | ✅ |
 | 🏗️ `architect` | Design structure & components | ❌ |
 | 📋 `planner` | High-level execution plan | ❌ |
 | ✂️ `splitter` | Break plan into atomic tasks | ❌ |
-| 🎤 `interviewer` | Ask clarifying questions (HITL) | ❌ |
+| 🎯 `composer` | Assemble task-specific dynamic pipelines | ❌ |
 | 🛠️ `worker` | Implement scoped changes | ✅ |
 | 🔨 `deep` | Multi-step complex worker | ✅ |
 | 👁️ `reviewer` | Self-critic / approve | ❌ |
@@ -148,7 +148,6 @@ Deep dive: **[docs/PROVIDERS.md](docs/PROVIDERS.md)**
 | 📝 `context` | Maintain CONTEXT.md | ❌ |
 | 📚 `docs` | Read documentation | ✅ |
 | 🧠 `memory` | Distill MEMORY.md | ❌ |
-| 🎓 `learner` | Wave lessons for future packs | ❌ |
 | 🗂️ `coordinator` | Manage board & task flow | ❌ |
 | 🎼 `orchestrator` | High-level coordination | ❌ |
 | 🚨 `escalate` | Arbitrate max-retry failures | ❌ |
@@ -197,8 +196,8 @@ slmcode studio --port-auto        → auto-switch if port is busy
 
 | Gate | Default | What it does |
 |------|---------|-------------|
-| 🎤 **Clarify** | `auto` | Interview agent asks about language/stack/framework |
-| ✅ **Plan approve** | `auto` | Human reviews plan before workers execute |
+| 🎤 **Clarify** | `ask` | Interview agent asks about language/stack/framework |
+| ✅ **Plan approve** | `ask` | Human reviews plan before workers execute |
 | 🔄 **Continue** | `ask` | Ask when retries exhausted — another wave or stop? |
 | 🚨 **Escalate** | `ask` | Task hit max retries — retry / re-scope / abort? |
 | 🐚 **Shell** | `allow` | Approve shell commands before execution |
@@ -237,7 +236,7 @@ static_quality: true      # reject stub/placeholder code
 | 🐘 Large-model habit | 🐭 SLMCode approach |
 |----------------------|---------------------|
 | Stuff the repo into chat | Incremental `.slmcode/*.md` memory |
-| One free-form agent | Plan → atomic tasks → 19 specialists |
+| One free-form agent | Plan → atomic tasks → 17 specialists |
 | Re-scan every turn | Reuse CONTEXT/MEMORY; skip deep explore |
 | Hope the model self-corrects | Reviewer ↔ corrector + multipass |
 | Opaque progress | Live CLI + Studio SSE stream |
@@ -254,6 +253,9 @@ slmcode init                         # auto-detects language & applies pack
 
 slmcode                              # premium TUI
 slmcode run -v "add JWT validation"
+slmcode compose "add JWT validation"      # preview selected phases/agents first
+slmcode readiness --fix                   # apply safe local-model defaults
+slmcode status                            # plan gate, diagnostics, latest composition
 slmcode board                        # live kanban
 slmcode studio                       # http://127.0.0.1:7420
 ```
@@ -264,7 +266,8 @@ Useful knobs:
 slmcode stack list
 slmcode stack apply deepseek         # switch to DeepSeek
 slmcode config set fast_model LFM2.5-8B-A1B-MLX-4bit   # speed boost!
-slmcode run --parallel 6 --think-passes 2 "refactor auth"
+slmcode run --dynamic --parallel 6 --think-passes 2 "refactor auth"
+slmcode run --no-dynamic "fix README typo" # force static pipeline for tiny jobs
 slmcode config set plan_approve ask  # require human plan approval
 slmcode blocks apply python          # apply Python language pack
 ```
@@ -280,7 +283,10 @@ slmcode blocks apply python          # apply Python language pack
 | `agent list` / `agent show` | Inspect agent specialists |
 | `blocks list` / `blocks apply` | Browse & apply building blocks |
 | `skills list` / `skills new` | Manage skill packs |
+| `compose` | Preview dynamic phases, specialists, handoff, and SLM fit |
+| `readiness` / `ready` | Score and optionally fix local SLM production settings |
 | `run -v` | Full pipeline + live stream |
+| `status` | Query, dynamic pipeline, plan gate, diagnostics, board counts |
 | `tui` / bare `slmcode` | Premium interactive TUI |
 | `chat` | Classic REPL |
 | `board` / `watch` | Colored kanban |
@@ -298,9 +304,11 @@ TUI: `/compact`, `/models`, `/mcp`, `/auth`, `/schema`, `/sessions`, `/stats`, `
 |---------|-----------|
 | ⚡ **Parallel execution** | 6 concurrent paths: workers, QA, critique, review, phases, speculative races |
 | 🏎️ **Dual-model** | `fast_model` routes light agents (reviewer, planner) to smaller/faster LLM |
+| 🎯 **Dynamic composition** | `compose` previews task-specific phases, agents, slots, handoff, and SLM fit |
 | 💨 **Wave fast-path** | Tasks with clean QA + disk evidence skip reviewer LLM entirely |
 | 🔄 **QA gate** | Single-round gate, auto-fixes gofmt/ruff, skips when no test files |
-| 🧪 **Smart smoke** | Uses `go vet` (instant) when no `*_test.go` files exist |
+| 🧪 **Smart smoke** | Uses fast local Go/Python/TypeScript checks when configured |
+| 🩺 **Readiness** | Scores provider/model reachability and safe SLM defaults before long runs |
 | 📦 **Auto-pack** | Detects `go.mod` / `pyproject.toml` / `package.json` on `init` |
 
 ---

cmd/slmcode/cmd_compose.go

@@ -69,19 +69,13 @@ With no query, prints the latest saved runtime composition from .slmcode/.`),
 }
 
 func readLatestComposition(slmDir string) (composer.Composition, error) {
-	var comp composer.Composition
-	path := filepath.Join(slmDir, composer.DynamicFileName)
-	b, err := os.ReadFile(path)
+	comp, ok, err := composer.LoadDynamic(slmDir)
 	if err != nil {
-		if os.IsNotExist(err) {
-			return comp, fmt.Errorf("no saved composition at %s — run `slmcode compose \"your task\"` to preview one", path)
-		}
 		return comp, err
 	}
-	if err := json.Unmarshal(b, &comp); err != nil {
-		return comp, fmt.Errorf("read latest composition: %w", err)
+	if !ok {
+		return comp, fmt.Errorf("no saved composition at %s — run `slmcode compose \"your task\"` to preview one", filepath.Join(slmDir, composer.DynamicFileName))
 	}
-	comp.Normalize()
 	return comp, nil
 }
 
@@ -113,6 +107,16 @@ func formatCompositionCLI(resp compositionCLIResponse) string {
 		b.WriteString(cli.Warn("dynamic_pipeline is disabled; this is an inspection preview"))
 		b.WriteString("\n")
 	}
+	if hints := compositionSLMFit(resp); len(hints) > 0 {
+		b.WriteString("\n")
+		b.WriteString(cli.Bold("SLM Fit"))
+		b.WriteString("\n")
+		for _, hint := range hints {
+			b.WriteString("  - ")
+			b.WriteString(hint)
+			b.WriteString("\n")
+		}
+	}
 
 	if len(c.Handoff) > 0 {
 		b.WriteString("\n")
@@ -188,6 +192,10 @@ func formatCompositionCLI(resp compositionCLIResponse) string {
 	return b.String()
 }
 
+func compositionSLMFit(resp compositionCLIResponse) []string {
+	return composer.FitHints(resp.Composition, resp.DynamicEnabled, resp.ModelProfile.ContextLimit)
+}
+
 func writeCLIKeyVal(b *strings.Builder, k, v string) {
 	if strings.TrimSpace(v) == "" {
 		v = "-"

cmd/slmcode/cmd_compose_test.go

@@ -38,6 +38,9 @@ func TestFormatCompositionCLIShowsAgentsHandoffAndLoop(t *testing.T) {
 	for _, want := range []string{
 		"Composition Preview",
 		"focused Go pipeline",
+		"SLM Fit",
+		"3 enabled phases selected",
+		"2 handoff bullets",
 		"Touch pkg/foo.go only",
 		"execute",
 		"go-worker",
@@ -60,6 +63,49 @@ func TestFormatCompositionCLIWarnsWhenDynamicDisabled(t *testing.T) {
 	if !strings.Contains(out, "dynamic_pipeline is disabled") {
 		t.Fatalf("missing disabled warning:\n%s", out)
 	}
+	if !strings.Contains(out, "enable dynamic_pipeline") {
+		t.Fatalf("missing SLM fit dynamic hint:\n%s", out)
+	}
+}
+
+func TestCompositionSLMFitFlagsWeakLocalComposition(t *testing.T) {
+	resp := compositionCLIResponse{
+		Mode:           "latest",
+		DynamicEnabled: true,
+		ModelProfile:   config.ModelProfile{ContextLimit: 4096},
+		Composition: composer.Composition{
+			Phases: []composer.PhaseChoice{
+				{ID: "context", Enabled: true},
+				{ID: "explore", Enabled: true},
+				{ID: "docs", Enabled: true},
+				{ID: "architect", Enabled: true},
+				{ID: "plan", Enabled: true},
+				{ID: "split", Enabled: true},
+				{ID: "coord", Enabled: true},
+				{ID: "execute", Agent: "worker", Enabled: true},
+				{ID: "test", Agent: "tester", Enabled: true},
+				{ID: "polish", Enabled: true},
+				{ID: "memory", Enabled: true},
+			},
+			Execute: composer.ExecuteChoice{DefaultRole: "worker", MaxWaves: 5},
+			Slots: []pipeline.Slot{
+				{ID: "a"}, {ID: "b"}, {ID: "c"}, {ID: "d"},
+			},
+		},
+	}
+	out := strings.Join(compositionSLMFit(resp), "\n")
+	for _, want := range []string{
+		"11 enabled phases",
+		"handoff is empty",
+		"team is empty",
+		"worker role is generic",
+		"max_waves=5",
+		"4 slots",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("hint missing %q:\n%s", want, out)
+		}
+	}
 }
 
 func TestReadLatestComposition(t *testing.T) {

cmd/slmcode/cmd_core.go

@@ -326,7 +326,7 @@ Examples:
 func statusCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "status",
-		Short: "Snapshot of query, plan head, board counts",
+		Short: "Snapshot of query, dynamic pipeline, plan gate, diagnostics, and board counts",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ws, err := openWorkspace()
 			if err != nil {
@@ -337,6 +337,10 @@ func statusCmd() *cobra.Command {
 			cli.KeyVal("provider", ws.Config.Provider)
 			cli.KeyVal("model", ws.Config.Model)
 			cli.KeyVal("backend", ws.Config.Backend)
+			fmt.Print(formatPipelineStatus(ws.Config))
+			if comp := formatLatestCompositionStatus(ws.Config); comp != "" {
+				fmt.Print(comp)
+			}
 			b := ws.Board.Snapshot()
 			by := b.ByColumn()
 			fmt.Println()
@@ -350,6 +354,9 @@ func statusCmd() *cobra.Command {
 			fmt.Println()
 			q, _ := ws.Store.Read("QUERY.md")
 			fmt.Println(cli.Dim(q))
+			if diag := formatLatestRunDiagnostics(ws.Config.SlmDir()); diag != "" {
+				fmt.Print(diag)
+			}
 			return nil
 		},
 	}

cmd/slmcode/cmd_doctor_test.go

@@ -0,0 +1,45 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/UnicoLab/slmcode/pkg/readiness"
+)
+
+func TestFormatDoctorProviderProbeReportsModelAvailability(t *testing.T) {
+	out := formatDoctorProviderProbe(readiness.Check{
+		ID:      "provider_model",
+		OK:      true,
+		Message: `omlx model "local-coder" available (2 listed)`,
+		Latency: 17,
+	})
+	for _, want := range []string{"LLM ok", "local-coder", "2 listed", "17 ms"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("output missing %q:\n%s", want, out)
+		}
+	}
+}
+
+func TestFormatDoctorProviderProbeExplainsMissingModel(t *testing.T) {
+	out := formatDoctorProviderProbe(readiness.Check{
+		ID:       "provider_model",
+		OK:       false,
+		Severity: "critical",
+		Message:  `omlx model "missing" not listed; available: other`,
+		Endpoint: "http://127.0.0.1:8000/v1",
+		FixLabel: "Select an installed model or update the stack",
+		FixHint:  "Use Settings -> Model Stack, or set model to one of the listed local models.",
+	})
+	for _, want := range []string{
+		"LLM check failed",
+		"missing",
+		"endpoint: http://127.0.0.1:8000/v1",
+		"tip: Use Settings",
+		"fix: Select an installed model",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("output missing %q:\n%s", want, out)
+		}
+	}
+}