Skip to content

Commit 996178b

Browse files
piotrlaczkowskipiotrlaczkowski
committed
docs: comprehensive v0.10.0 documentation update
## New - docs/blocks.md: 296-line building blocks reference (schema, discovery, predefined packs, CLI, Studio, custom blocks, marketplace) - Blocks section in FAQ (switching packs, custom blocks, discovery order) - Language pack switch recipe in recipes.md ## Updated - changelog.md: v0.10.0 entry with building blocks, language packs, one-click switching - cli.md: blocks command reference + deep dive section - pipeline.md: predefined presets table, quick-start with blocks apply, API examples - studio.md: BlockManager + PackSelector in layout zones - concepts.md: Building blocks concept (#5) with discovery order + four block kinds - config.md: active_pack, active_pipeline fields - architecture.md: blocks + stacks packages in package map - quickstart.md: init + blocks apply go in playground setup - testing.md: blocks apply in five-minute smoke test - index.md: building blocks pill in hero meta - mkdocs.yml: blocks.md page in navigation
1 parent 6689426 commit 996178b

14 files changed

Lines changed: 486 additions & 4 deletions

‎docs/architecture.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,14 @@ If you stuff the whole repo into context, don’t be surprised when the model na
3131
cmd/slmcode CLI + embedded Studio (go:embed ui/)
3232
pkg/orchestrator Pipeline runner + coordinator + sessions
3333
pkg/pipeline Config-driven phases / slots / loop agents
34+
pkg/blocks Building block registry + bundled YAML presets
3435
pkg/loop Parallel execute → review → correct
3536
pkg/agents Specialist prompts + custom YAML factory
37+
pkg/stacks Provider/model stack presets
3638
pkg/plan Kanban, sanitize, discover
3739
pkg/context Markdown store + TaskPack budgeter
40+
pkg/quality QA gate runner + smoke checks
41+
pkg/skills SKILL.md loader
3842
pkg/knowledge SKILLS.md + learned evolution
3943
pkg/learning Wave lessons / deltas
4044
pkg/instructions AGENTS.md / PROJECT loader
@@ -43,7 +47,6 @@ pkg/permissions auto | dry-run | review
4347
pkg/multipass Think → critique → refine
4448
pkg/stream Live events (CLI + SSE)
4549
pkg/server Studio HTTP + SSE
46-
pkg/skills SKILL.md loader
4750
pkg/workspace Real FS/git tools
4851
pkg/backends OpenAI-compat / Ollama / optional CLIs
4952
pkg/harness Public embed API

‎docs/blocks.md‎

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
# 🧱 Building Blocks
2+
3+
> Marketplace-ready YAML presets — share, remix, and discover pipelines, agents, quality packs, and language packs.
4+
5+
<div class="slm-banner" markdown>
6+
<span class="slm-banner__emoji">🧱</span>
7+
<p class="slm-banner__text" markdown>
8+
<strong>Blocks are the foundation of extensibility.</strong> Every pipeline, every specialist agent, every quality check — all defined as portable YAML that anyone can create, share, and apply.
9+
</p>
10+
</div>
11+
12+
---
13+
14+
## What are Building Blocks?
15+
16+
Blocks are **versioned, marketplace-ready YAML packages** that define reusable configurations for the SLMCode pipeline. They come in four kinds:
17+
18+
| Kind | Schema | Purpose |
19+
|------|--------|---------|
20+
| `pipeline` | `PipelineBlock` | Phase graph, loop agents, insertable slots |
21+
| `agent` | `AgentBlock` | Custom specialist definition or builtin override |
22+
| `quality` | `QualityBlock` | Format/lint/test/build commands per language |
23+
| `pack` | `PackBlock` | Composes pipeline + quality + agents + skills |
24+
25+
---
26+
27+
## Discovery Order
28+
29+
Blocks are discovered in a priority chain. **First ID wins per kind:**
30+
31+
1. **Project** — `.slmcode/blocks/{pipelines,agents,quality,packs}/*.yaml`
32+
2. **User** — `~/.slmcode/blocks/…` or `$XDG_CONFIG_HOME/slmcode/blocks/…`
33+
3. **Extra** — `$SLMCODE_BLOCKS` env var, walk-up `blocks/` dirs
34+
4. **Builtin** — embedded in `pkg/blocks/bundled/` (compiled into binary)
35+
36+
This means **project overrides** always win. Drop a `.slmcode/blocks/pipelines/go.yaml` with your customizations, and it replaces the builtin Go pipeline for that project.
37+
38+
---
39+
40+
## Common Schema (Meta)
41+
42+
Every block YAML file shares this header:
43+
44+
```yaml
45+
api_version: blocks/v1 # required — current schema version
46+
kind: pipeline # pipeline | agent | quality | pack
47+
id: my-block # lowercase kebab-case, 2-64 chars, [a-z][a-z0-9_-]+
48+
name: My Block # human-readable display name
49+
description: A reusable block
50+
version: "1.0.0"
51+
author: UnicoLab
52+
license: MIT
53+
language: go # lowercase language code
54+
tags: [go, worker]
55+
icon: "🐹"
56+
shareable: true # marketplace-ready flag (default: true)
57+
```
58+
59+
---
60+
61+
## Predefined Language Packs (Builtin)
62+
63+
SLMCode ships with **three production-ready language packs:**
64+
65+
### 🐹 Go
66+
67+
```
68+
Pipeline: go | Agents: go-worker, go-tester | Quality: go
69+
```
70+
71+
- **Pipeline**: Go-aware execute phase with `go-tester` agent
72+
- **Worker**: Module-aware, uses `go test ./<pkg> -short` after edits
73+
- **Tester**: Full verify chain — `gofmt` → `go vet` → `go test -race` → `go build`
74+
- **QA Gate**: `go test ./... -race -count=1`
75+
76+
### 🐍 Python
77+
78+
```
79+
Pipeline: python | Agents: python-worker, python-tester | Quality: python
80+
```
81+
82+
- **Pipeline**: Python-aware with `python-tester` agent
83+
- **Worker**: PyProject-aware, smokes with `py_compile` + `pytest`
84+
- **Tester**: `ruff check` → `mypy` → `pytest` (uv-aware)
85+
- **QA Gate**: `python -m pytest -q` (or `uv run pytest -q`)
86+
87+
### ⚛️ React / TypeScript
88+
89+
```
90+
Pipeline: react | Agents: react-worker, react-tester | Quality: react
91+
```
92+
93+
- **Pipeline**: Frontend-aware with `react-tester` agent
94+
- **Worker**: Vite/Next-aware, smokes with `tsc --noEmit`
95+
- **Tester**: `npm run lint` → `tsc --noEmit` → `npm test` → `npm run build`
96+
- **QA Gate**: `npm test --silent`
97+
98+
---
99+
100+
## CLI Commands
101+
102+
```bash
103+
# List all available blocks, grouped by kind
104+
slmcode blocks list
105+
106+
# Show details of a specific block
107+
slmcode blocks show pipeline go
108+
slmcode blocks show agent python-worker
109+
slmcode blocks show pack react
110+
111+
# Apply a language pack (writes pipeline.yaml + config)
112+
slmcode blocks apply go
113+
slmcode blocks apply go --materialize-agents
114+
115+
# Validate all block YAML configs
116+
slmcode blocks validate
117+
```
118+
119+
In the interactive chat REPL:
120+
121+
```
122+
/pack go — apply the Go language pack
123+
/pack python — apply the Python language pack
124+
/blocks — list all available blocks
125+
```
126+
127+
---
128+
129+
## Creating Custom Blocks
130+
131+
### Pipeline Block
132+
133+
Save as `.slmcode/blocks/pipelines/my-pipeline.yaml`:
134+
135+
```yaml
136+
api_version: blocks/v1
137+
kind: pipeline
138+
id: my-lang
139+
name: My Language Pipeline
140+
version: "1.0.0"
141+
language: rust
142+
tags: [rust, pipeline]
143+
icon: "🦀"
144+
spec:
145+
version: 1
146+
order: [init, skills, context, explore, plan, split, coord, execute, learn, test, memory, done]
147+
groups:
148+
- {id: prepare, label: Prepare, steps: [init, skills, context, explore]}
149+
- {id: design, label: Design, steps: [plan, split]}
150+
- {id: build, label: Build, steps: [coord, execute, learn]}
151+
- {id: verify, label: Verify, steps: [test]}
152+
- {id: finish, label: Finish, steps: [memory, done]}
153+
phases:
154+
init: {agent: "", when: always, label: Init}
155+
context: {agent: context, when: always, label: Context}
156+
explore: {agent: explorer, when: auto, label: Explore}
157+
plan: {agent: planner, when: always, label: Plan}
158+
split: {agent: splitter, when: always, label: Split}
159+
coord: {agent: coordinator, when: always, label: Coord}
160+
execute: {agent: worker, when: always, label: Execute}
161+
test: {agent: tester, when: always, label: Test}
162+
memory: {agent: memory, when: always, label: Memory}
163+
done: {agent: "", when: always, label: Done}
164+
execute:
165+
default_role: worker
166+
reviewer: reviewer
167+
corrector: corrector
168+
max_waves: 2
169+
slots:
170+
- id: quality-reminder
171+
agent: tester
172+
title: Quality reminder
173+
before: execute
174+
when: always
175+
persist_to: scratch
176+
fail_mode: continue
177+
input: |
178+
Remember quality bar: cargo clippy, cargo test, cargo build
179+
Query: {{query}}
180+
```
181+
182+
### Agent Block
183+
184+
Save as `.slmcode/blocks/agents/my-worker.yaml`:
185+
186+
```yaml
187+
api_version: blocks/v1
188+
kind: agent
189+
id: my-worker
190+
name: My Worker
191+
version: "1.0.0"
192+
language: rust
193+
tags: [rust, worker]
194+
icon: "🦀"
195+
spec:
196+
id: my-worker
197+
title: My Worker
198+
system_prompt: |
199+
You are a Rust implementation specialist. Stay inside HARD SCOPE.
200+
After edits, smoke with: cargo test -p <crate>
201+
tools: true
202+
max_iter: 16
203+
temperature: 0.12
204+
max_tokens: 3072
205+
skills: [specialist-worker, atomic-coding]
206+
```
207+
208+
### Quality Block
209+
210+
Save as `.slmcode/blocks/quality/my-lang.yaml`:
211+
212+
```yaml
213+
api_version: blocks/v1
214+
kind: quality
215+
id: my-lang
216+
name: My Lang Quality
217+
version: "1.0.0"
218+
language: rust
219+
spec:
220+
detect:
221+
files: [Cargo.toml]
222+
extensions: [.rs]
223+
priority: 20
224+
lint:
225+
- {cmd: cargo clippy -- -D warnings, label: clippy}
226+
test:
227+
- {cmd: cargo test, label: cargo test}
228+
build:
229+
- {cmd: cargo build, label: cargo build}
230+
smoke: cargo test --quiet
231+
qa_gate: cargo test
232+
safe_prefixes:
233+
- cargo test
234+
- cargo build
235+
- cargo clippy
236+
```
237+
238+
### Pack Block
239+
240+
Save as `.slmcode/blocks/packs/my-lang.yaml`:
241+
242+
```yaml
243+
api_version: blocks/v1
244+
kind: pack
245+
id: my-lang
246+
name: My Language Pack
247+
version: "1.0.0"
248+
language: rust
249+
spec:
250+
pipeline: my-lang
251+
quality: my-lang
252+
agents: [my-worker, my-tester]
253+
skills: [atomic-coding]
254+
pin_skills: true
255+
override_tester: my-tester
256+
override_worker: my-worker
257+
```
258+
259+
---
260+
261+
## Studio Integration
262+
263+
The **BlockManager** page (navigate to Blocks in the sidebar) provides a visual browser for all available blocks:
264+
265+
- **Tabbed interface**: All, Packs, Pipelines, Agents, Quality
266+
- **Cards** showing metadata: name, description, language, version, tags, source
267+
- **One-click Apply** for packs and pipelines
268+
- **Active indicators** showing which pack/pipeline is currently active
269+
270+
The **PackSelector** in Settings lets you switch language packs directly from the settings page, alongside the Stack Selector.
271+
272+
The **PipelineEditor** includes a preset selector that lets you switch between predefined pipeline configurations (Go, Python, React) with one click.
273+
274+
---
275+
276+
## Validation
277+
278+
```bash
279+
slmcode blocks validate
280+
```
281+
282+
Loads every block, calls `Validate()` on each, and for packs also verifies that all referenced pipelines, agents, and quality packs actually exist. Reports exact errors so you can fix YAML issues before running.
283+
284+
---
285+
286+
## Marketplace-Ready
287+
288+
All blocks are designed for sharing:
289+
290+
- **Versioned** — Semantic versioning (`"1.0.0"`)
291+
- **Authored** — `author` and `license` fields
292+
- **Tagged** — `tags` for discovery and filtering
293+
- **Iconed** — `icon` for visual recognition in UI
294+
- **Shareable** — `shareable: true` flag for marketplace listing
295+
296+
Drop your custom blocks into a GitHub repo's `blocks/` directory, and anyone can use them by setting the `SLMCODE_BLOCKS` environment variable.

‎docs/changelog.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,33 @@
11
# Changelog
22

3+
## v0.10.0 — Building Blocks, Language Packs & One-Click Pipeline Switching
4+
5+
### Highlights
6+
- **Building Blocks system** — Marketplace-ready YAML presets: pipelines, agents, quality packs,
7+
language packs. Four block kinds with `api_version: blocks/v1` schema.
8+
- **Predefined language packs** — 🐹 Go, 🐍 Python, ⚛️ React/TypeScript ready to use.
9+
Each pack includes tuned pipeline, language-specific worker/tester agents, and quality gates.
10+
- **Blocks CLI** — `slmcode blocks list|show|apply|validate` — full block lifecycle management.
11+
- **Chat REPL commands** — `/blocks` lists all blocks, `/pack <id>` applies a language pack.
12+
- **BlockManager UI** — New Studio page: tabbed browser for all blocks, one-click apply,
13+
active indicators, source badges (builtin/custom).
14+
- **PipelineEditor enhancement** — Preset selector for one-click switching between
15+
Go/Python/React pipelines directly from the pipeline editor.
16+
- **PackSelector in Settings** — Switch language packs from the Settings page,
17+
alongside the existing Stack Selector.
18+
- **Active config indicators** — LiveView and Sidebar now show active pack, pipeline,
19+
and stack badges during runs.
20+
- **AGENTS.md** — Comprehensive 416-line contributor guide at project root.
21+
- **18 blocks tests** — Full test coverage: registry loading, validation, catalog filtering,
22+
quality detection, QA gate resolution, meta validation, edge cases.
23+
24+
### Fixes
25+
- Import cycle resolved: `blocks → agents → workspace → quality → blocks`.
26+
Quality smoke detection now delegates to `blocks.ResolveQAGateCommand` in orchestrator layer.
27+
- `active_pack` and `active_pipeline` fields added to config schema and Studio Config type.
28+
29+
---
30+
331
## v0.9.0 — Stacks, auth store & strict-provider ReAct
432

533
### Highlights

‎docs/cli.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ slmcode <command> --help
5050
| `init` | Create `.slmcode/` scaffolding 🌱 |
5151
| `stack` | list / show / apply provider+model presets 📦 |
5252
| `agent` | list / show / set per-agent LLM pins 🧩 |
53+
| `blocks` | list / show / apply / validate building blocks 🧱 |
5354
| `update` | Refresh binary (release) or rebuild from source ⬆️ |
5455
| `version` | Print version metadata |
5556

@@ -124,6 +125,30 @@ slmcode agent set worker --model … --provider … # pin; empty = inherit stac
124125
Stacks live in `stacks/*.yaml`. DeepSeek default endpoint: `https://api.deepseek.com`
125126
(OpenAI-compat client appends `/v1`). Details → [🔌 Providers](providers.md).
126127

128+
## `blocks` 🧱
129+
130+
```bash
131+
# List all building blocks, grouped by kind
132+
slmcode blocks list
133+
134+
# Show details of a specific block
135+
slmcode blocks show pipeline go
136+
slmcode blocks show agent python-worker
137+
slmcode blocks show pack react
138+
139+
# Apply a language pack (writes pipeline.yaml + config)
140+
slmcode blocks apply go
141+
slmcode blocks apply python --materialize-agents
142+
slmcode blocks apply react --force
143+
144+
# Validate all block YAML configs
145+
slmcode blocks validate
146+
```
147+
148+
Blocks are marketplace-ready YAML presets: pipelines, agents, quality packs, and language packs.
149+
Three predefined language packs ship built-in: 🐹 Go, 🐍 Python, ⚛️ React/TypeScript.
150+
Custom blocks go in `.slmcode/blocks/`. Details → [🧱 Blocks](blocks.md).
151+
127152
## `config` ⚙️
128153

129154
```bash

0 commit comments

Comments
 (0)