@zerwiz/ymir 0.1.34 → 0.1.35

package/apps/smidja-factory/references/handoff.md

@@ -0,0 +1,161 @@
+# Handoff Reference
+
+The envelope schema, the two-channel output contract, and the session directory layout — how context transfers in code, not in conversation.
+
+## Two output channels, exactly
+
+An agent may produce output in two ways and no others:
+
+1. **Reference files** written into `context_handoff/` — plans, notes, artifacts for the agents that follow.
+2. **A final valid-JSON response** — the envelope, its direct response and nothing else.
+
+Code does the rest: parse the response against the output type the call declared, persist it as `envelope.json`, and inject it into the next agent's user prompt.
+
+## Envelope schema
+
+Every output type extends `EnvelopeBase`:
+
+```python
+class EnvelopeBase(BaseModel):
+    status: Literal["success", "fail"]  # the only required field
+    summary: str = ""                   # one sentence: what happened
+    artifacts: list[str] = []           # paths written, usually inside context_handoff/
+    notes_for_next_agent: str = ""      # what the next agent must know
+```
+
+`status` is load-bearing: an envelope that parses but reports `status="fail"` raises, failing the phase. An agent declaring its own failure is not a successful phase.
+
+The starter types in `smidja_modules/data_types.py`:
+
+```python
+class GenericOutput(EnvelopeBase):
+    """Fallback for an agent with no sharper contract yet."""
+
+class PlanOutput(EnvelopeBase):
+    commit_message: str = ""            # imperative git subject for the PLAN FILE itself
+
+class BuildOutput(EnvelopeBase):
+    changed_files: list[str] = []
+    commit_message: str = ""            # consumed by the git commit phase
+
+class ScoutOutput(EnvelopeBase):
+    findings: list[ScoutFinding] = []   # ScoutFinding: {file: str, note: str}
+
+class ReviewOutput(EnvelopeBase):
+    approved: bool = False              # the verdict; status is only "did the review run"
+    findings: list[ReviewFinding] = []  # ReviewFinding: {requirement, met: bool, evidence}
+    blocking: list[str] = []            # what must change before approval
+
+class DocumentOutput(EnvelopeBase):
+    document_path: str = ""             # the write-up's home in the repo
+    documented_files: list[str] = []
+    commit_message: str = ""
+```
+
+`commit_message` defaults to empty, so a git phase consuming it always needs a fallback — see `cookbooks/create_adw.md`.
+
+**Each `commit_message` describes its own agent's work product, never the next one's**: `PlanOutput`'s covers the spec file, `BuildOutput`'s the code, `DocumentOutput`'s the write-up. A chain that commits once can use whichever fits; a chain that commits per step (`smidja_simple_sdlc.py`) needs all three, and reusing one agent's sentence for another's diff is how a commit log starts lying.
+
+There is no test output type: running the suite is a `kind="code"` phase, and its `QualityResult` reaches the next agent through `quality.as_envelope`.
+
+Two of these are adapters rather than agent reports — code shaped as an envelope so an agent can be handed a deterministic result through the same door: `VerifyOutput` (a lint/test block's result) and `ChangesOutput` (a captured `git diff`, from `changes.as_envelope`). The consuming agent cannot tell the difference, which is the point.
+
+The envelope is a **manifest of claims**. Gates verify those claims after the fact — declared artifacts exist and are non-empty, declared changes appear in the diff, declared tests actually pass. See `cookbooks/update_modules.md`.
+
+## The typed-output rule
+
+**Every agent call passes a concrete output type**, and the agent's final JSON is parsed against exactly that type. No untyped handoffs.
+
+```python
+plan = ph.call(AgentCall(output_type=PlanOutput, prompt=prompt,
+                         gates=[gates.artifacts_exist]))
+```
+
+The user prompt asks for the shape; the type enforces it. They always travel as a pair, which is what lets one agent serve many calls — same system prompt, different user prompt + output type per call site. Output types live in code, never in `smidja.config.yaml`.
+
+**Parse failure is not a restart.** If the response doesn't parse or doesn't validate, the harness re-prompts the **same session** with a correction naming the required fields — bounded by `JSON_FIX_ATTEMPTS` in `agents.py` (2). Gate violations use the identical mechanism, bounded instead by the phase's `retries`. A cold restart would throw away the context that produced the near-miss.
+
+In v1 there is no separate continue call to make: `agent_pi.run()` passes `--session-id`, which pi treats as create-or-continue, so running an agent and continuing it are the same call with the same id. Before parsing, the harness also tolerates a fenced `json` code block or prose wrapped around the object — but the prompt still asks for bare JSON, and every failed attempt is persisted as an invalid envelope row.
+
+## Injecting the previous envelope
+
+`prompts.py` renders the agent's `user.md`, substituting:
+
+| Placeholder | Value |
+|---|---|
+| `{{prompt}}` | the engineer's ask (or the smidja's per-call prompt) |
+| `{{previous_envelope}}` | the upstream envelope JSON, from `AgentCall(previous=...)` |
+| `{{context_handoff_dir}}` | absolute path to this session's `context_handoff/` |
+
+A `user.md` declares one h3 per incoming datum, then the task, then the output contract:
+
+````markdown
+# Scout Task
+
+## Variables
+
+### prompt
+
+{{prompt}}
+
+### previous_envelope
+
+{{previous_envelope}}
+
+### context_handoff_dir
+
+{{context_handoff_dir}}
+
+## Task
+
+Find what `prompt` asks about. Write findings into `context_handoff_dir`, then emit your `Report` JSON.
+
+## Report
+
+Respond with ONLY valid JSON matching `ScoutOutput` — no prose before or after:
+
+```json
+{
+  "status": "success",
+  "summary": "<one sentence on what you found>",
+  "findings": [
+    { "file": "src/server.ts", "note": "<why this file matters>" }
+  ],
+  "artifacts": ["<context_handoff_dir>/scout_findings.md"]
+}
+```
+````
+
+The `## Report` section shows the exact JSON shape of the declared output type — that is the agent's output contract, and it lives in `user.md` because the shape belongs to the *use*, not the identity. The matching `system.md` stays static: Purpose + Instructions only.
+
+## Session directory layout
+
+```
+smidja/smidja_data/sessions/{smidja_id}/
+├── agent_map.json          agent name → coding-agent session_id + model
+├── context_handoff/        the ONE place agents write files for the agents that follow
+└── {agent_name}/
+    ├── prompts/            exact prompts sent (system.md + user.md), saved before execution
+    ├── pi_sessions/        pi's own session state for this agent
+    ├── raw_output.jsonl    full JSONL stream from the coding agent, appended live
+    └── envelope.json       the final valid-JSON response — captured, validated, persisted by code
+```
+
+`session.ensure(cfg, smidja_id)` mints or joins the id and creates these dirs. One `context_handoff/` per session, shared by every agent — the single location for cross-agent files.
+
+## agent_map.json and resuming
+
+```json
+{
+  "planner": {"session_id": "smidja-a1b2c3d4-planner-9f2e",
+              "model": "google/gemini-3.6-flash", "coding_agent": "pi"},
+  "builder": {"session_id": "smidja-a1b2c3d4-builder-71ac",
+              "model": "google/gemini-3.6-flash", "coding_agent": "pi"}
+}
+```
+
+This map is the key that lets a later smidja rejoin each agent's **existing context window**. Run `smidja_build.py --smidja-id a1b2c3d4` after `smidja_plan.py` and the builder resumes its own session rather than starting cold.
+
+The map records the model each session was created with. If config drift changes an agent's model, that agent starts a **fresh** session and the map is updated — never a bad resume. `agent_sessions` in `smidja.db` is the queryable mirror of this file.
+
+**Files are the raw record; the db is the queryable mirror.** Losing `smidja.db` loses nothing that can't be rebuilt from `raw_output.jsonl`, `envelope.json`, and `agent_map.json`.

package/apps/smidja-factory/references/observability.md

@@ -0,0 +1,166 @@
+# Observability Reference
+
+The event schema, the seven SQLite tables, and the polling contract — the one data path is **agents → sqlite → web ui**.
+
+## Two stores, one truth
+
+**Files are the raw record** (`raw_output.jsonl` streams, `envelope.json`, `agent_map.json`); **SQLite (`smidja.db`) is the queryable mirror** the UI reads. `tracer.py` writes both. Losing the db loses nothing that can't be rebuilt from files.
+
+Location comes from `observability.db` in `smidja.config.yaml`, default `smidja/smidja_data/smidja.db` — inside the **target** repo, gitignored.
+
+## Event schema
+
+`tracer.py` emits these types, every one logged against its `smidja_id` **and** `phase_id`:
+
+| Type | Emitted when |
+|---|---|
+| `phase_start` | a `run.phase(...)` block is entered |
+| `agent_start` | a coding agent is spawned or resumed for `ph.call(...)` |
+| `tool_call` | a tool (`read`, `bash`, `edit`, `write`) returns — **one event per real call**, named `bash: ls -la src`, payload `{tool, tool_call_id, args, result_snippet, ok, duration_ms, agent}` |
+| `handoff` | an envelope crosses from one agent to the next |
+| `gate_pass` | a gate found no failed checks — payload carries `attempt`, `checks` (the evidence), and an empty `violations` |
+| `gate_fail` | a gate found at least one failed check — payload carries `attempt`, `checks`, and `violations` |
+| `log` | an explicit `ph.log(...)` from the smidja script |
+| `agent_end` | the agent's run completes; envelope parsed or not — payload carries `cost`, `usage` (the per-component breakdown), `context_tokens`, `context_window` |
+| `phase_end` | the block exits; carries the resolved status |
+| `error` | a raise inside a phase block |
+
+`parent_id` nests spans, so an agent phase expands into its tool-call spans in the UI.
+
+**Spend is itemised per phase.** `agent_end.usage` carries tokens *and* dollars for each component pi reports — `input`, `output`, `cache_read`, `cache_write` — summed across every send the phase made, so a phase that retried on a bad envelope or a failed gate shows what all its attempts cost, not just the last one. The four components sum to `total_tokens`, and their costs sum to `total_cost`; the visualizer's Cost panel renders them as a table you can add up by eye.
+
+`reasoning_tokens` is the thinking share and is **inside** `output_tokens`, not a fifth component — measured across every session on disk, reasoning never exceeds output and the four components always reconcile to the total. It bills at the output rate, so the panel nests it under output rather than adding it. Runs predating the breakdown have no `usage` key at all; the lump `cost` and the event's own `tokens` still stand, and the UI says so rather than rendering zeroes.
+
+**Context is occupancy, not spend.** `events.tokens` and `sessions.total_tokens` bill every turn, so they only grow — an agent that burned 100k tokens may be sitting in a 15k window. `context_tokens` is how full the window actually was when the agent stopped, which is what the visualizer's per-lane Context bar measures against `context_window`.
+
+It is computed the way pi computes it for its own footer and its auto-compaction trigger (`calculateContextTokens` in the coding agent's `core/compaction/compaction.ts`): take the last *valid* assistant turn — skipping `aborted` and `error` turns — and read `usage.totalTokens`, falling back to `input + output + cacheRead + cacheWrite`. Cache reads count; cached prompt is still prompt. `context_window` is the same `contextWindow` pi reads from `~/.pi/agent/models.json`, so `context_tokens / context_window` is the number pi would show. Both are NULL on rows written before the columns existed, and the lane draws no bar rather than a misleading empty one.
+
+Two caveats worth knowing. Pi adds an *estimate* for any messages trailing the last assistant usage; in a batch (`-p`) run the session ends on that message, so the two agree. And if auto-compaction fires as the very last act of a run, the recorded number is the pre-compaction size — pi itself reports `null` in that window rather than guessing.
+
+**Gates record evidence, not just a verdict.** A gate returns one `{item, ok, note}` check per thing it looked at, and `violations` are derived from the failed ones. Both land in `gate_results` (`checks_json` + `violations_json`) and in the `gate_pass`/`gate_fail` payload, so a green gate can answer *what did you verify* — `{"item": "…/plan.md", "ok": true, "note": "exists, 454B"}` — rather than only *did it pass*. Rows written before this existed have `checks_json` NULL; treat that as "no evidence recorded", not "nothing checked".
+
+The gate event payload carries `attempt` too, so the `gate_results` table and the event stream are equivalent sources — a live consumer can group gate results per correction round from events alone, without a second query.
+
+**A `tool_call` is the one event that spans time**, so it fills both `started_at` and `ended_at` on the row — the tool's real start and return. Every other type is a point in time: `started_at` is when it was recorded and `ended_at` stays NULL. Lay tool calls out on a time axis from those columns, never by parsing `payload_json` (`duration_ms` is in the payload too, as pi's own number, but it is a convenience, not the source for layout).
+
+**Streaming is solved by construction.** `agent_pi.py` tails pi's JSONL stdout line by line and the tracer inserts each event into `smidja.db` **while the agent is still working** — never batched at phase end (verified in the first smoke run: tool calls visible mid-run). Everything downstream is a poll → render.
+
+## Tables
+
+```sql
+sessions (
+  smidja_id        TEXT PRIMARY KEY,
+  request       TEXT,              -- the engineer's ask
+  status        TEXT,              -- running | success | fail
+  engineer      TEXT,
+  started_at    TEXT, ended_at TEXT,
+  total_tokens  INTEGER, total_cost REAL
+);
+
+phases (
+  phase_id      TEXT PRIMARY KEY,
+  smidja_id        TEXT REFERENCES sessions,
+  seq           INTEGER,
+  name TEXT, kind TEXT, owner TEXT, description TEXT,
+  status        TEXT DEFAULT 'fail',   -- success must be earned
+  attempt       INTEGER DEFAULT 0, retries INTEGER DEFAULT 0,
+  error         TEXT,
+  started_at    TEXT, ended_at TEXT
+);
+
+events (
+  event_id      TEXT PRIMARY KEY,
+  smidja_id        TEXT REFERENCES sessions,
+  phase_id      TEXT REFERENCES phases,   -- every event logs against smidja + phase
+  parent_id     TEXT,                     -- span nesting
+  type          TEXT,   -- phase_start | phase_end | agent_start | agent_end | tool_call
+                        -- | handoff | gate_pass | gate_fail | log | error
+  name          TEXT,
+  payload_json  TEXT,
+  tokens        INTEGER,
+  started_at    TEXT, ended_at TEXT   -- ended_at set only on events that span time
+);
+
+envelopes (
+  envelope_id   TEXT PRIMARY KEY,
+  smidja_id        TEXT REFERENCES sessions,
+  phase_id      TEXT REFERENCES phases,
+  agent         TEXT,
+  output_type   TEXT,              -- name of the data_types model it parsed against
+  payload_json  TEXT,
+  valid         INTEGER,
+  attempt       INTEGER,
+  created_at    TEXT
+);
+
+gate_results (
+  id            INTEGER PRIMARY KEY,
+  smidja_id        TEXT REFERENCES sessions,
+  phase_id      TEXT REFERENCES phases,
+  attempt       INTEGER,
+  gate          TEXT,
+  passed        INTEGER,
+  violations_json TEXT,             -- derived: the failed checks, as "item: note"
+  checks_json   TEXT,               -- [{item, ok, note}] — everything the gate looked at
+  created_at    TEXT
+);
+
+processes (                        -- smidja_id → pid, so a stuck run can be stopped
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  smidja_id        TEXT REFERENCES sessions,
+  kind          TEXT,               -- 'smidja' (the workflow process) | 'agent' (a coding-agent child)
+  name          TEXT,               -- '' for the smidja, the agent name for a child
+  pid           INTEGER,
+  command       TEXT,               -- what the pid WAS; pids get recycled, so verify before killing
+  started_at    TEXT, ended_at TEXT -- ended_at NULL = believed alive
+);
+
+agent_sessions (                   -- the queryable mirror of agent_map.json
+  smidja_id        TEXT REFERENCES sessions,
+  agent         TEXT,
+  coding_agent  TEXT, model TEXT, color TEXT,   -- color: the config's lane swatch
+  session_id    TEXT,
+  context_tokens INTEGER,           -- window occupancy after the agent's last turn
+  context_window INTEGER,           -- the model's ceiling, from the pi registry
+  created_at    TEXT, last_used_at TEXT,
+  PRIMARY KEY (smidja_id, agent)
+);
+```
+
+**A hung agent emits nothing**, which is exactly when you need its pid: no events, no tokens, no output to read. `processes` is the only table that can answer "what is this run running, and how do I stop it" — `just procs <smidja_id>` lists what is live, `just kill <smidja_id>` stops children before the parent, and both verify the recorded `command` still matches the pid before signalling it. A killed run finalizes its own trace: SIGTERM and SIGINT are turned into `SystemExit` in `session.ensure`, so the session lands on `fail` with its process rows closed instead of reading `running` forever.
+
+**Every agent earns a lane the same way:** a `phases` row with `kind='agent'` and a non-null `owner`, plus its own spans. Manifest agents get this from `run.phase(...)`. An orchestrator subagent spawned via opencode's `task` tool gets it from `agents._materialize_subagent(run, phase, parent_agent, event)`: the `subagent_dispatch` forwarder branch writes that phase row + spans (`phase_start` → `agent_start` → `subagent_dispatch` → `agent_end` → `phase_end`) in the same shape as a manifest agent, so the visualizer draws it as its own lane stacked under the dispatcher. The subagent runs inside the dispatcher's opencode session, so its lane inherits the dispatcher's configured model/coding surface; its live `session_id` and context occupancy are unknown at completion, so they are omitted (no context bar, honest label). **No `agent_sessions` row is written for a dispatch** — that table's key is `(smidja_id, agent)`, so a task-dispatched `scout` must never overwrite a same-named manifest scout. Because the dispatch event is terminal (opencode reports the task *result*), these lanes are written at completion with `started_at` ≈ `ended_at`; the UI's minimum block width keeps them readable. Subagent lane `seq = parent.seq + 1000 + <counter>` (per-run `_subagent_counter` in `runner.py`), so they sort after every manifest phase and never collide.
+
+**Historical runs** (recorded before this fix) can be backfilled with
+`python3 scripts/backfill-subagent-lanes.py <smidja.db> [--apply]` — it replays the
+same materialization from stored `subagent_dispatch` events (idempotent, backs
+up first). It only fingerprints dispatches whose `phase_id` is a manifest phase
+(`NOT LIKE '%::%'`), so the backfill's own span events can never cascade.
+
+**Derived, never stored:** phase durations (`ended_at − started_at`), session phase-progress (query `phases` by `smidja_id`), lane layout (`kind` + `owner`).
+
+Phase status invariants: `queued` only for manifest-declared phases not yet entered (dashed in the UI); `running` on enter; only a clean exit writes `success` — agent phases additionally need the envelope parsed and gates green; everything else resolves to `fail`.
+
+## WAL pragmas
+
+Open **every** connection — writer and reader — with:
+
+```sql
+PRAGMA journal_mode=WAL;
+PRAGMA synchronous=NORMAL;
+PRAGMA busy_timeout=5000;
+```
+
+WAL allows readers during writes. Writers are the tracers of running smidja processes; concurrent writers are fine given one small transaction per event plus `busy_timeout`. The visualizer reads on a readonly connection with exactly one exception: archiving a session (`POST /api/sessions/:smidja_id/archive`) opens a second connection to set `sessions.archived`. That flag is review triage — it says a human has looked at the run — so it is the reader's state living on the row, and no tracer ever writes or reads it.
+
+## Polling contract
+
+**The UI never receives pushes.** No ingest endpoint, no WebSocket, no backfill or dedup logic.
+
+Live view polls on a rowid cursor every `observability.poll_ms` (default 500):
+
+```sql
+SELECT ... FROM events WHERE smidja_id = ? AND rowid > ? ORDER BY rowid LIMIT 500;
+```
+
+Keep the highest `rowid` returned as the next cursor. History is **the same queries** with filters, lazy-paged as the engineer scrolls or drills in — one mechanism serves both live and past runs, which is why there is no separate replay path.

package/apps/smidja-factory/scripts/install.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = []
+# ///
+"""/install — stamp the smithy from the skill into the cwd. Idempotent.
+
+Usage:
+    uv run <skill>/scripts/install.py [--force]
+
+Stamps: smidja/ (modules + starter smidja), smidja/smidja_data/prompt_engineering/
+(4 starter agents), smidja/smidja_smidja_config/smidja.config.yaml, .env.sample,
+.gitignore entries.
+Existing files are skipped unless --force.
+"""
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+TEMPLATES = Path(__file__).resolve().parent.parent / "templates"
+
+GITIGNORE_ENTRIES = [
+    "smidja/smidja_data/sessions/",
+    "smidja/smidja_data/smidja.db*",
+    ".env",
+    # The smidja are Python, so importing smidja_modules writes bytecode next to it.
+    # Chains that end in a commit phase call `git add -A`, so without this a
+    # stamped repo commits its own .pyc files — 15 of them showed up in the
+    # first repo that was ever installed into from scratch.
+    "__pycache__/",
+    "*.pyc",
+]
+
+
+def stamp(src: Path, dest: Path, force: bool, stamped: list, skipped: list) -> None:
+    if src.is_dir():
+        for child in sorted(src.iterdir()):
+            if child.name == "__pycache__":
+                continue
+            stamp(child, dest / child.name, force, stamped, skipped)
+        return
+    if dest.exists() and not force:
+        skipped.append(str(dest))
+        return
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dest)
+    stamped.append(str(dest))
+
+
+def ensure_gitignore(root: Path, stamped: list) -> None:
+    gitignore = root / ".gitignore"
+    existing = gitignore.read_text().splitlines() if gitignore.exists() else []
+    missing = [e for e in GITIGNORE_ENTRIES if e not in existing]
+    if missing:
+        with gitignore.open("a") as f:
+            f.write("\n# smidja runtime\n" + "\n".join(missing) + "\n")
+        stamped.append(f"{gitignore} (+{len(missing)} entries)")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--force", action="store_true", help="overwrite existing files")
+    args = parser.parse_args()
+
+    root = Path.cwd()
+    stamped, skipped = [], []
+
+    # Fail with a plain reason when the target cannot be written, rather than an
+    # os.mkdir traceback mid-stamp.
+    if not os.access(root, os.W_OK):
+        print(f"error: {root} is not writable — run install.py from a writable repo root",
+              file=sys.stderr)
+        return 1
+
+    try:
+        stamp(TEMPLATES / "smidja", root / "smidja", args.force, stamped, skipped)
+        stamp(TEMPLATES / "prompt_engineering",
+              root / "smidja" / "smidja_data" / "prompt_engineering", args.force, stamped, skipped)
+        stamp(TEMPLATES / "harness_engineering",
+              root / "smidja" / "smidja_data" / "harness_engineering", args.force, stamped, skipped)
+        stamp(TEMPLATES / "smidja.config.yaml",
+              root / "smidja" / "smidja_smidja_config" / "smidja.config.yaml",
+              args.force, stamped, skipped)
+        stamp(TEMPLATES / "env.sample", root / ".env.sample", args.force, stamped, skipped)
+        # The recipes are part of the operating experience, and several cookbooks
+        # plus the run banner tell you to use them, so a stamped repo has to have
+        # them. Skipped like any other file if the repo already has a justfile.
+        stamp(TEMPLATES / "justfile", root / "justfile", args.force, stamped, skipped)
+        ensure_gitignore(root, stamped)
+    except PermissionError as exc:
+        print(f"error: cannot write {exc.filename} — {exc.strerror}", file=sys.stderr)
+        return 1
+
+    print(f"smidja installed into {root}")
+    print(f"  stamped: {len(stamped)} file(s)")
+    for s in stamped:
+        print(f"    + {s}")
+    if skipped:
+        print(f"  skipped (already exist, use --force to overwrite): {len(skipped)}")
+    print("\nnext steps:")
+    print("  1. cp .env.sample .env   # then set the key(s) your roster needs")
+    print("  2. just demo             # two cheap read-only runs, end to end")
+    print("  3. just sessions         # what just happened")
+    print("  4. just obs              # the trace UI, needs bun")
+    print("\n  no just? the raw form of step 2 is:")
+    print("     uv run smidja/smidja_prompt.py \"say hello\" --agent scout")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/apps/smidja-factory/scripts/make_config.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = []
+# ///
+"""make_config — generate smidja/smidja_smidja_config/smidja.config.yaml with great defaults.
+
+Usage:
+    uv run <skill>/scripts/make_config.py [--force]
+"""
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+TEMPLATE = Path(__file__).resolve().parent.parent / "templates" / "smidja.config.yaml"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+
+    dest = Path.cwd() / "smidja" / "smidja_smidja_config" / "smidja.config.yaml"
+    if dest.exists() and not args.force:
+        print(f"{dest} already exists — use --force to overwrite")
+        return 1
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(TEMPLATE, dest)
+    print(f"wrote {dest}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/apps/smidja-factory/scripts/make_smidja.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = []
+# ///
+"""make_adw — generate a new one-shot smidja script from agents in the config.
+
+Usage:
+    uv run <skill>/scripts/make_adw.py --name review_docs --agents scout,builder
+
+Each named agent becomes one agent phase, chained by envelope. Starter agents
+map to their concrete output types; unknown agents get GenericOutput (define a
+concrete type in smidja_modules/data_types.py and swap it in).
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+OUTPUT_TYPES = {"planner": "PlanOutput", "builder": "BuildOutput",
+                "scout": "ScoutOutput",
+                "reviewer": "ReviewOutput", "documenter": "DocumentOutput"}
+
+HEADER = '''#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml"]
+# ///
+"""smidja {title} — generated by make_adw.
+
+Usage:
+    uv run smidja/smidja_{name}.py "<prompt or path/to/prompt.md>" [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> {chain}
+"""
+
+import argparse
+import sys
+
+from smidja_modules import agents, gates, session, utils
+from smidja_modules.data_types import AgentCall, PhaseParams, {imports}
+
+REQUIRED_AGENTS = {agents_list}
+
+
+def main(prompt: str, config: str = "smidja/smidja_smidja_config/smidja.config.yaml", smidja_id: str | None = None) -> int:
+    cfg = agents.load_config(config)
+    agents.validate(cfg, REQUIRED_AGENTS)
+    run = session.ensure(cfg, smidja_id)
+
+    with run.phase(PhaseParams(name="request", kind="engineer", owner=run.engineer,
+                               description="Capture the incoming ask")) as ph:
+        ph.log(input=prompt)
+
+    previous = None
+{phases}
+    return 0 if run.succeeded else 1
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("prompt", help="inline text or a path to a prompt file")
+    parser.add_argument("--config", default="smidja/smidja_smidja_config/smidja.config.yaml")
+    parser.add_argument("--smidja-id", default=None, help="join or pin an existing session")
+    args = parser.parse_args()
+    sys.exit(main(utils.resolve_prompt(args.prompt), args.config, args.smidja_id))
+'''
+
+PHASE = '''    # TODO: replace this description — say what THIS phase does and why.
+    with run.phase(PhaseParams(name="{name}", kind="agent", owner="{agent}",
+                               description="Run {agent} over the request and hand its envelope on")) as ph:
+        previous = ph.call(AgentCall(output_type={output_type}, prompt=prompt,
+                                     previous=previous,
+                                     gates=[gates.artifacts_exist]))
+'''
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--name", required=True, help="snake_case smidja name")
+    parser.add_argument("--agents", required=True, help="comma-separated agent names, in order")
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+
+    agent_names = [a.strip() for a in args.agents.split(",") if a.strip()]
+    if not agent_names:
+        print("no agents given")
+        return 1
+
+    types = [OUTPUT_TYPES.get(a, "GenericOutput") for a in agent_names]
+    seen: dict[str, int] = {}
+    phases = []
+    for agent, output_type in zip(agent_names, types):
+        seen[agent] = seen.get(agent, 0) + 1
+        phase_name = agent if seen[agent] == 1 else f"{agent}_{seen[agent]}"
+        phases.append(PHASE.format(name=phase_name, agent=agent, output_type=output_type))
+
+    body = HEADER.format(
+        title=args.name.replace("_", " ").title(),
+        name=args.name,
+        chain=" -> ".join(agent_names),
+        imports=", ".join(sorted(set(types))),
+        agents_list=repr(sorted(set(agent_names))),
+        phases="\n".join(phases),
+    )
+
+    dest = Path.cwd() / "smidja" / f"smidja_{args.name}.py"
+    if dest.exists() and not args.force:
+        print(f"{dest} already exists — use --force to overwrite")
+        return 1
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(body)
+    print(f"wrote {dest}")
+    print("next: replace each phase description — a generated one says nothing, "
+          "and the description is the only intent the trace ever shows")
+    print(f"run: uv run smidja/smidja_{args.name}.py \"your request\"")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())