Skip to content

Commit f846762

Browse files
piotrlaczkowskipiotrlaczkowski
committed
docs: premium Material theme and expanded handbook
Ship a polished MkDocs experience with ocean-slate branding, deeper getting-started/handbook/reference pages, and clearer navigation for daily use of the harness.
1 parent bf8c32b commit f846762

22 files changed

Lines changed: 1905 additions & 771 deletions

‎README.md‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -182,18 +182,15 @@ TUI: `/compact`, `/sessions`, `/stats`, `/permission`, `/agents`, `/stop`, `/res
182182

183183
## 📚 Docs
184184

185-
**Site (MkDocs → GitHub Pages):** [unicolab.github.io/smlcode](https://unicolab.github.io/smlcode/)
186-
187-
| Page | When |
188-
|------|------|
189-
| [Install](docs/install.md) | One-liners, brew, Windows, uninstall |
190-
| [Quick start](docs/quickstart.md) | First green run in ~60s |
191-
| [Providers](docs/providers.md) | Any LLM — presets, keys, per-agent |
192-
| [User guide](docs/guide.md) | Daily CLI / Studio workflow |
193-
| [Studio](docs/studio.md) | GUI + HTTP/SSE API |
194-
| [Agents](docs/agents.md) | Specialist roster |
195-
| [Testing](docs/testing.md) | Smoke test, Studio, e2e |
196-
| [Architecture](docs/architecture.md) | Internals |
185+
**Premium site (MkDocs Material → GitHub Pages):**
186+
[unicolab.github.io/smlcode](https://unicolab.github.io/smlcode/)
187+
188+
| Section | Pages |
189+
|---------|--------|
190+
| Getting started | Install · Quick start · Concepts · Providers |
191+
| Handbook | Guide · TUI · Skills · Studio · Agents · Recipes |
192+
| Reference | CLI · Config · Testing · FAQ |
193+
| Internals | Architecture · Contributing |
197194

198195
Local preview: `make docs-serve` → http://127.0.0.1:8000
199196

‎docs/agents.md‎

Lines changed: 35 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,97 @@
11
# 🧩 Agents
22

3-
Fourteen specialists. One kanban board. Zero “please hold the entire repo in your head” fantasies.
4-
5-
All agents register with GoLangGraph `SubAgentExecutor` and receive **scoped TaskPacks** — never the whole monorepo gift-wrapped as a prompt.
3+
Fourteen specialists. Scoped packs. No “hold the monorepo in your head” cosplay.
64

75
!!! tip "Mix brains"
8-
Per-agent providers let you run a cheap local explorer and a sharper cloud reviewer in the same pipeline. See [Providers](providers.md).
6+
Cheap local explorer + sharper cloud reviewer in one run — [Providers](providers.md).
97

108
---
119

12-
## 👥 Roster (14)
10+
## Roster
1311

1412
| ID | Tools | Output | When |
1513
|----|-------|--------|------|
16-
| `coordinator` | — | JSON actions | Pre-execute + after each wave |
17-
| `orchestrator` | — | short decisions | Registered / reserved |
18-
| `context` | — | CONTEXT.md body | Start of run |
19-
| `explorer` | ✅ | JSON file map | When deep explore needed |
20-
| `docs` | ✅ | JSON docs map | Docs/API/README queries |
21-
| `architect` | — | JSON design | Design/refactor/large queries |
22-
| `planner` | — | JSON plan | Always (multipass) |
23-
| `splitter` | — | JSON tasks | Always (multipass) |
24-
| `worker` | ✅ | JSON status | Kanban execute |
25-
| `deep` | ✅ | JSON status | Multi-step tasks (`--role deep`) |
26-
| `reviewer` | — | JSON approve | Self-critic per task |
27-
| `corrector` | ✅ | JSON status | On review reject |
28-
| `tester` | ✅ | JSON passed | End validation |
29-
| `memory` | — | markdown bullets | End + wave learn |
30-
31-
List live:
14+
| `coordinator` | — | JSON actions | Pre-exec + each wave |
15+
| `orchestrator` | — | decisions | Reserved |
16+
| `context` | — | CONTEXT body | Run start |
17+
| `explorer` | ✅ | file map | Deep explore |
18+
| `docs` | ✅ | docs map | Docs/API queries |
19+
| `architect` | — | design JSON | Large/refactor |
20+
| `planner` | — | plan JSON | Always |
21+
| `splitter` | — | tasks JSON | Always |
22+
| `worker` | ✅ | status | Execute |
23+
| `deep` | ✅ | status | Multi-step |
24+
| `reviewer` | — | approve JSON | Critic |
25+
| `corrector` | ✅ | status | On reject |
26+
| `tester` | ✅ | passed | End validation |
27+
| `memory` | — | bullets | Learn |
3228

3329
```bash
3430
curl -s localhost:7420/api/agents | jq '.[].id'
35-
# Studio → Agents
36-
# TUI → /agents
31+
# TUI: /agents
3732
```
3833

3934
---
4035

41-
## 🛠️ Custom agents
36+
## Custom agents
4237

43-
Persist under `.slmcode/agents/<id>.yaml` (or `~/.slmcode/agents/`).
38+
`.slmcode/agents/<id>.yaml` or `~/.slmcode/agents/`.
4439

4540
```bash
46-
# TUI wizard or key=value
47-
/agent new
48-
/agent new id=night-auditor title=Night provider=openai endpoint=http://127.0.0.1:9000/v1
49-
/agent edit worker model=qwen2.5-coder:14b # builtin override
41+
/agent new id=night-auditor title=Night provider=ollama model=qwen2.5-coder:14b
42+
/agent edit worker model=qwen2.5-coder:14b
5043
/agent show night-auditor
51-
/agent delete night-auditor
5244
```
5345

54-
Fields: `skills`, `model`, `provider`, `endpoint`, `tools`, `temperature`, `max_tokens`, `max_iter`, `system_prompt` — same store as `POST/PUT/DELETE /api/agents`.
55-
56-
### Per-agent endpoints
46+
Fields: `skills`, `model`, `provider`, `endpoint`, `tools`, `temperature`, `max_tokens`, `max_iter`, `system_prompt`.
5747

58-
YAML/UI keep friendly names (`provider: openai`). When `endpoint` (or API key) differs, the runtime registers a unique backend key such as `openai@http://host:9000/v1` so two agents with the same provider name never share the wrong gateway.
48+
Different endpoints → unique backend keys (no accidental shared gateway).
5949

6050
---
6151

62-
## 🎯 Coordinator actions
63-
64-
The coordinator doesn't write code. It **steers the board**.
52+
## Coordinator actions
6553

6654
```json
6755
{
68-
"summary": "Auth path is clear; tests still missing",
56+
"summary": "Auth clear; tests missing",
6957
"actions": [
7058
{"type": "promote", "task_id": "T2", "text": "deps met"},
7159
{"type": "reassign", "task_id": "T3", "role": "deep"},
7260
{"type": "add_task", "text": "Add regression test", "role": "tester"},
73-
{"type": "note", "task_id": "T1", "text": "watch edge case"}
61+
{"type": "note", "task_id": "T1", "text": "edge case"}
7462
],
7563
"focus_files": ["pkg/foo.go"]
7664
}
7765
```
7866

7967
---
8068

81-
## 📤 Delegating
69+
## Delegating
8270

8371
```bash
8472
slmcode task add "Deep refactor auth" --role deep --column ready_to_dev
8573
slmcode task delegate T1 docs
8674
```
8775

88-
Studio task inspector → role dropdown includes all specialists.
89-
9076
---
9177

92-
## 📜 Project instructions (auto-loaded)
78+
## Project instructions
9379

94-
Drop any of these at the repo root (or under `.slmcode/`):
80+
Auto-loaded from:
9581

9682
- `AGENTS.md` / `AGENT.md`
9783
- `CLAUDE.md`
9884
- `.cursorrules`
9985
- `.slmcode/PROJECT.md`
10086

101-
They're injected into specialist packs at run start. Teach the crew your house style once; stop repeating yourself forever.
102-
10387
!!! example "Tiny AGENTS.md"
10488
```markdown
10589
# Agents
106-
107-
- Prefer tiny, reviewable diffs
108-
- Table-driven tests in Go
109-
- Never rewrite unrelated files "while you're there"
90+
- Tiny, reviewable diffs
91+
- No drive-by refactors
92+
- Match existing style
11093
```
11194

95+
→ [Skills](skills.md) · [Concepts](concepts.md)
96+
11297
Made with ♥ by [UnicoLab](https://unicolab.ai)

‎docs/architecture.md‎

Lines changed: 38 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -4,128 +4,70 @@ How SLMCode stays sharp when the model is small, tired, or both.
44

55
---
66

7-
## 🎯 Design thesis
7+
## Design thesis
88

9-
30B-class SLMs fail when asked to “be a frontier agent” in one giant free-form loop.
9+
30B-class SLMs fail when asked to “be a frontier agent” in one free-form loop.
1010

11-
SLMCode keeps **routing in Go** and gives each specialist a **tiny scoped pack**:
11+
**Routing in Go. Tiny packs per specialist. Disk evidence over vibes.**
1212

13-
- selected `.slmcode/*.md` slices
14-
- a few focus files
15-
- matched + learned skills
16-
- **one** atomic task
13+
!!! quote "Turkey rule"
14+
If you stuff the whole repo into context, don't be surprised when the model naps.
1715

18-
!!! quote "The turkey rule"
19-
If you stuff the whole repo into context, don't be surprised when the model falls asleep at the table.
16+
→ Narrative version: [Concepts](concepts.md)
2017

2118
---
2219

23-
## 📦 Package map
20+
## Package map
2421

2522
```text
26-
cmd/slmcode CLI + embedded Studio UI
27-
pkg/orchestrator Code-driven pipeline + coordinator + sessions
28-
pkg/loop Parallel execute → review → correct (+ live events)
29-
pkg/agents Specialist prompts + factory (14 roles)
30-
pkg/plan Kanban, sanitize, filesystem discover
23+
cmd/slmcode CLI + embedded Studio (go:embed ui/)
24+
pkg/orchestrator Pipeline + coordinator + sessions
25+
pkg/loop Parallel execute → review → correct
26+
pkg/agents 14 specialist prompts + factory
27+
pkg/plan Kanban, sanitize, discover
3128
pkg/context Markdown store + TaskPack budgeter
32-
pkg/knowledge Auto SKILLS.md + learned skill evolution
33-
pkg/learning Wave lessons / context deltas
29+
pkg/knowledge SKILLS.md + learned evolution
30+
pkg/learning Wave lessons / deltas
3431
pkg/instructions AGENTS.md / PROJECT loader
35-
pkg/session Resumable run snapshots
36-
pkg/permissions auto | dry-run | review write policy
32+
pkg/session Resumable snapshots + ReAct resume
33+
pkg/permissions auto | dry-run | review
3734
pkg/multipass Think → critique → refine
38-
pkg/stream Live event schema (CLI + SSE)
35+
pkg/stream Live events (CLI + SSE)
3936
pkg/server Studio HTTP + SSE
4037
pkg/skills SKILL.md loader
41-
pkg/workspace Real FS/git tools (ws_*, git_*)
42-
pkg/backends OpenAI-compat / Ollama / optional CLI backends
43-
pkg/harness Public New / OpenWorkspace API
44-
pkg/cli Colored terminal + live event formatter
45-
pkg/config Provider presets + project config
46-
pkg/repair SLM JSON repair helpers
38+
pkg/workspace Real FS/git tools
39+
pkg/backends OpenAI-compat / Ollama / optional CLIs
40+
pkg/harness Public embed API
41+
pkg/cli Terminal UX
42+
pkg/config Presets + project config
43+
pkg/repair SLM JSON repair
44+
pkg/retrieval Embeddings / lexical ranking
4745
```
4846

4947
---
5048

51-
## 📡 Live streaming
49+
## Live streaming
5250

53-
`stream.Event` (alias `orchestrator.Event`):
54-
55-
| Field | Meaning |
56-
|-------|---------|
57-
| `phase` | Pipeline stage |
58-
| `kind` | `phase` / `agent_start` / `agent_end` / `coord` / `learn` / `output` |
59-
| `agent` | Specialist id |
60-
| `task_id` | Kanban task |
61-
| `scope` | Focus files |
62-
| `output` | Truncated agent output |
63-
64-
Consumed by CLI (`cli.PrintEvent`), Studio SSE (`GET /api/events`), and `GET /api/runs/latest`.
65-
66-
---
67-
68-
## ♻️ Explore reuse
69-
70-
If CONTEXT is rich, MEMORY/PROJECT exist, and filesystem discovery finds relevant files, the explorer deep-dive is **skipped**. Later runs stay fast and consistent with accumulated knowledge.
71-
72-
```bash
73-
SLMCODE_FORCE_EXPLORE=1 slmcode run "…" # force a fresh dig
74-
```
75-
76-
---
77-
78-
## 🔁 Self-critic loop
79-
80-
```text
81-
worker/deep → reviewer (JSON) → corrector (tools) → reviewer …
82-
```
83-
84-
Heuristics trust clear `status:done` + `files_changed` when reviewers get flaky. Disk evidence beats vibes.
85-
86-
---
87-
88-
## 🦋 Knowledge flywheel
89-
90-
After each run:
91-
92-
1. MEMORY.md append (lessons)
93-
2. CONTEXT.md append (run complete)
94-
3. `knowledge.Evolve` → `SKILLS.md` + `skills/learned/SKILL.md`
95-
4. PROJECT.md auto-notes for touched files
96-
5. Session JSON under `.slmcode/sessions/`
97-
98-
The project gets smarter. You get less typing. Everybody wins (except bugs).
51+
`stream.Event` fields: `phase`, `kind`, `agent`, `task_id`, `scope`, `output`.
52+
Consumers: CLI, Studio SSE (`/api/events`), `/api/runs/latest`.
9953

10054
---
10155

102-
## 🧵 Parallelism & deps
56+
## Explore reuse · critic · flywheel
10357

104-
`SubAgentExecutor` runs ready kanban tasks up to `max_parallel`.
105-
Blocked upstream deps are soft-skipped so one failed locate task cannot freeze the whole board.
58+
- **Reuse** when CONTEXT/MEMORY are rich (override with `SLMCODE_FORCE_EXPLORE=1`)
59+
- **Critic**: worker → reviewer → corrector loop; disk evidence preferred
60+
- **Flywheel**: MEMORY / CONTEXT / SKILLS / sessions after each run
10661

10762
---
10863

109-
## 🔐 Permissions
64+
## Parallelism
11065

111-
Workspace tools honor `config.permission`:
112-
113-
| Mode | Behavior |
114-
|------|----------|
115-
| `auto` | Write |
116-
| `dry-run` | Simulate |
117-
| `review` | Stage JSON patches under `.slmcode/pending/` for `slmcode apply` |
66+
`SubAgentExecutor` runs ready tasks up to `max_parallel`. Soft-skip blocked deps so one stuck locate can't freeze the board.
11867

11968
---
12069

121-
## 📎 Dependency
122-
123-
```text
124-
slmcode ──go.mod──► github.com/piotrlaczkowski/GoLangGraph
125-
└── optional local replace for hacking
126-
```
127-
128-
Embed the harness:
70+
## Embed
12971

13072
```go
13173
import "github.com/UnicoLab/slmcode/pkg/harness"
@@ -135,4 +77,8 @@ _ = h.Init()
13577
res, err := h.Run(ctx, "refactor pkg/auth")
13678
```
13779

80+
Dependency: `github.com/piotrlaczkowski/GoLangGraph` (optional local replace for hacking).
81+
82+
→ [Contributing](contributing.md)
83+
13884
Made with ♥ by [UnicoLab](https://unicolab.ai)

0 commit comments

Comments
 (0)