devstuff 1.15.0__tar.gz → 1.16.0__tar.gz

{devstuff-1.15.0 → devstuff-1.16.0}/CHANGELOG.md

@@ -1,3 +1,25 @@
+## v1.16.0 (2026-07-24)
+
+### Feat
+
+- **agent**: first-run setup wizard for agent configuration
+- **agent**: multi-line input and slash completion in the REPL
+- **agent**: milestone 4 — transcripts, /history, docs, schema
+- **agent**: complete milestone 2 — tools, sandbox denylist, approval loop
+- **agent**: add workspace sandbox, launch guard, and smoke suite
+- **agent**: add ollama-backed agent scaffold (milestone 1)
+
+### Fix
+
+- **agent**: correct argument mapping and output capture for function tools
+
+## v1.15.1 (2026-07-20)
+
+### Fix
+
+- make aws update idempotent (pass --update over existing install)
+- repair broken update paths for llm-checker and ruby
+
 ## v1.15.0 (2026-07-18)
 
 ### Feat

{devstuff-1.15.0 → devstuff-1.16.0}/CLAUDE.md

@@ -167,6 +167,78 @@ non-interactive `bash <tmpfile>`, so `~/.bashrc`/nvm's shell init never runs on
 Not yet built: an `add` wizard and `catalog import`/`export` for functions, analogous to the
 ones tools already have.
 
+## Specs (`docs/specs/`)
+
+Design documents live in `docs/specs/<feature>/` — `specifications.md` (numbered, testable
+requirements), `stack-decisions.md` (choices *and* rejected alternatives with reasons), and
+`development-plan.md` (milestones, testing strategy, risks). See `docs/specs/README.md` for the
+conventions.
+
+When working on a feature that has a spec, read it first and **keep it current in the same PR** —
+a spec that no longer matches the code is worse than no spec. Record resolved open questions with
+a date and the answer rather than deleting them, and when a live finding contradicts a
+requirement, update the requirement and note what was learned. New features of any size should
+get a spec directory before implementation starts.
+
+## The agent (`devstuff agent`) — a third catalog subsystem
+
+`src/dev_setup/agent/` + `agent_tools.yaml` is an interactive session where a local Ollama model
+calls devstuff's tools plus a workspace-scoped filesystem/shell kit. It follows the same
+catalog-driven shape as tools and functions: `agent/catalog.py` validates `agent_tools.yaml`
+(bundled → user override), `agent/registry.py` turns it into `AgentTool` objects, and
+`agent/primitives.py` dispatches by `impl` through a `_PRIMITIVES` dict — the same
+strategy-dispatch pattern as `_INSTALLERS` in `generic.py`.
+
+**Adding an agent tool**: if it bridges to something that already exists (a catalog tool, a
+`functions.yaml` entry), it is a pure YAML edit — `impl: catalog` or `impl: function` plus a
+`target`. Only a genuinely new mechanism needs a new `impl: primitive` callable registered in
+`_PRIMITIVES`. `type: script` functions are auto-exposed as `fn_<key>` tools with no edit at all.
+
+**Security invariants — do not weaken these without deliberate thought:**
+- `Workspace.resolve()` in `agent/sandbox.py` is the *only* thing standing between the model and
+  the filesystem. It resolves symlinks and `..` **before** the containment check; reordering that
+  reintroduces a symlink escape. Prompt instructions are not a control and never will be.
+- The command denylist (`check_command`) runs **before** any confirmation prompt and is
+  deliberately not disabled by `--yolo`. The prompt is a human attention filter; attention
+  degrades over a session, the denylist does not.
+- Credential dirs are blocked for **read** as well as write — exfiltrating an SSH key into a model
+  context is as bad as overwriting one. `~/.config/dev-setup` is readable but not writable, so
+  the agent cannot author catalogs (FR-14a).
+- `assess()` (the launch guard) is advisory UX, not a control. Keep that distinction in comments;
+  the risk is a future reader mistaking a warning for enforcement.
+
+**Everything in the loop returns errors to the model rather than raising.** Unknown tool, bad
+arguments, sandbox refusal, a crashing tool — all become `role: tool` messages so the agent can
+re-plan. A malformed tool call must never end a session. `max_iterations` is what stops a runaway.
+
+**`cd` is a tool, not a shell command**, for the same reason `shell-eval` functions exist: each
+`run_command` is its own subprocess, so a shell `cd` evaporates on exit. And `shell-eval`
+functions are excluded from the toolbox entirely — they exist to mutate the calling shell, which
+an agent subprocess has no way to do (mirroring the guard in `run_cmd.py`).
+
+**Ollama response-shape handling all lives in `ollama.parse_message()`.** Builds differ on
+whether reasoning arrives in `message.thinking` or as inline `<think>` tags in `content`, and
+whether tool calls arrive in `tool_calls` or as JSON inside `content`. Think-stripping must stay
+*ahead* of the content-JSON fallback, or a reasoning preamble hides the tool call. Keep new
+quirks in that one function.
+
+**Model choice is measured, not assumed.** `ollama show` reports a `capabilities` array;
+preflight requires `tools` in it. The default (`gemma4:latest`) was picked by running the same
+scaffolding prompt across local models — lfm2.5 had `write_file` available and still shelled out
+to `echo >`, corrupting the content through shell quoting. If you change the default, re-run that
+comparison rather than reasoning from parameter counts.
+
+`agent_tools.schema.json` is hand-maintained for editor tooling and **not** enforced at runtime —
+same arrangement, and same drift hazard, as `functions.schema.json`.
+
+First-run UX: `agent/wizard.py` builds `agent.yaml` on the first interactive run (host → a
+pick-list of tool-capable models → reasoning visibility), re-runnable via `devstuff agent
+--setup`. It configures only those three fields deliberately — a first-run wizard asking about
+`num_ctx` and timeouts would be worse than one asking nothing; everything else keeps its default
+and is hand-editable.
+
+Not yet built: an `add` wizard for agent tools, and `catalog import`/`export` for them.
+
 ## Key design decisions (don't relitigate these)
 
 - **uv owns Python provisioning.** The bash wrapper only guarantees `uv` is present; Python
@@ -179,6 +251,13 @@ ones tools already have.
   fields, bad `requires` all raise `CatalogError` immediately rather than silently degrading.
 - **Custom install/remove scripts are plain strings**, written to a temp file at run time, so
   `bash` gets full script-parsing fidelity instead of `bash -c "..."` string quoting problems.
+- **The agent's safety boundary is the workspace root, enforced in code.** Not a sandbox
+  technology (bubblewrap/firejail) and not model instructions — `Path.resolve()` containment plus
+  a command denylist, both unit-tested. Chosen so it works with zero new dependencies and fails
+  closed; if you want stronger isolation, add it *around* this, not instead of it.
+- **No new runtime dependencies for the agent.** The Ollama transport is stdlib `urllib` against
+  `/api/chat`; the REPL uses `prompt_toolkit`, already vendored via questionary. devstuff is a
+  globally installed CLI, so every dependency is a cost paid by users who never run `agent`.
 - **Functions get a parallel catalog/registry instead of extending `GenericTool`.** The
   schemas diverge enough (no `requires` inference, a `params` list, no install/remove
   lifecycle) that folding them into the tool catalog would be lossy; some duplication with

{devstuff-1.15.0 → devstuff-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devstuff
-Version: 1.15.0
+Version: 1.16.0
 Summary: Development environment setup CLI for Linux
 Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
 Author-email: Sawyer <sawyerksu@gmail.com>
@@ -291,6 +291,160 @@ confirmation.
 
 ---
 
+## Agent
+
+`devstuff agent` opens an interactive session with a **local** model (via [Ollama](https://ollama.com))
+that can call devstuff's own tools plus a workspace-scoped filesystem/shell kit. Nothing leaves
+the machine, there are no API keys, and it works offline.
+
+```bash
+devstuff agent                                  # interactive REPL
+devstuff agent --setup                          # (re)run the configuration wizard
+devstuff agent --dir ~/projects                 # skip the workspace prompt
+devstuff agent --model granite4.1:8b            # override the configured model
+devstuff agent --print "which node tools do I have?"   # one-shot, non-interactive
+```
+
+```
+you ❯ create a python project called xyz-project with a hello world main.py
+
+  ↳ run_command(command='mkdir xyz-project')
+
+  ╭─ run in ./xyz-project ──────────────────────╮
+  │ mkdir xyz-project                           │
+  ╰─────────────────────────────────────────────╯
+  ? Run run_command?  Yes / No / Always allow this tool
+```
+
+### Setup
+
+First, make sure a tool-capable model is available:
+
+```bash
+devstuff install ollama
+ollama pull gemma4          # or any model reporting the `tools` capability
+```
+
+Then the **first time you run `devstuff agent`** with no configuration, a wizard walks you
+through it — Ollama host, then a pick-list of your locally available tool-capable models, then
+whether to show the model's reasoning. It writes `~/.config/dev-setup/agent.yaml` and continues
+into the session. Re-run it any time with `devstuff agent --setup`.
+
+The wizard only lists models that report the `tools` capability (`ollama show <model>` shows it
+under Capabilities), so you can't accidentally pick one that can't call tools. `devstuff agent`
+re-verifies this at startup regardless, and tells you which local models qualify if the
+configured one doesn't.
+
+The wizard is skipped when you pass `--model`/`--host` (you're already steering) or run
+non-interactively (`--print`), which fall back to built-in defaults.
+
+### Safety model
+
+The workspace root, chosen at launch (prompted, defaulting to the current directory), is the
+boundary:
+
+- **Path containment** — every path a tool touches is resolved (collapsing `..` and following
+  symlinks) and must land inside the workspace root. A symlink planted inside the workspace is
+  not a way out.
+- **Protected paths** — `~/.ssh`, `~/.aws`, `~/.gnupg` and `~/.config/gh` are refused for read
+  *and* write even if the workspace root contains them. `~/.config/dev-setup` is readable but
+  never writable: catalog authoring stays a human action.
+- **Confirmation** — every mutating tool call shows the exact command, or a unified diff for
+  `write_file`, and waits for yes / no / always-this-session. Read-only calls run silently.
+- **Denylist** — `sudo`, pipe-to-shell installers, catastrophic deletes, disk and service
+  commands, and redirects out of the workspace are refused before any prompt is shown, and are
+  **not** enabled by `--yolo`.
+- **Launch guard** — warns before handing the agent `$HOME`, a system directory, or a git repo
+  with uncommitted changes.
+
+`--yolo` skips confirmations for a session; the denylist and path containment still apply.
+In `--print` mode without `--yolo`, mutating calls are refused rather than auto-approved, so a
+scripted invocation cannot become an unattended agent with write access.
+
+### Configuration
+
+`~/.config/dev-setup/agent.yaml` (all fields optional):
+
+```yaml
+version: 1
+model: gemma4:latest
+host: http://localhost:11434     # a remote daemon works; the local binary is then not required
+temperature: 0.2
+num_ctx: 16384
+think: false                     # true renders the model's reasoning, dimmed
+max_iterations: 12               # tool calls per turn before the loop gives up
+request_timeout: 120
+command_timeout: 120
+max_tool_output_bytes: 8000      # tool output is truncated to this before going back to the model
+auto_approve: []                 # tool keys that never ask, e.g. ["write_file"]
+deny_patterns: []                # extra regexes refused on top of the built-in denylist
+```
+
+### Tools
+
+| Tool | Mutating | Purpose |
+|------|----------|---------|
+| `read_file` | | Read a UTF-8 file in the workspace |
+| `write_file` | ! | Create or overwrite a file (shows a diff) |
+| `list_dir` | | List a directory |
+| `cd` | | Move the working directory used by later calls |
+| `run_command` | ! | Run a shell command in the workspace |
+| `list_tools` | | List the devstuff catalog with install state |
+| `search_catalog` | | Find a catalog tool by name or description |
+| `tool_info` | | Details for one catalog tool |
+| `install_tool` | ! | Install a catalog tool (handles sudo itself) |
+| `fn_<key>` | ! | Every `type: script` entry in `functions.yaml`, exposed automatically |
+
+`cd` is a tool rather than a shell command because each `run_command` is its own subprocess — a
+shell `cd` would evaporate when it exits. `shell-eval` functions are deliberately excluded: they
+exist to mutate the calling shell, which a subprocess cannot do.
+
+### agent_tools.yaml
+
+The toolbox is a catalog, like everything else. Bundled at `src/dev_setup/agent_tools.yaml`,
+user overrides at `~/.config/dev-setup/agent_tools.yaml`, same merge precedence as `tools.yaml`.
+
+```yaml
+version: 1
+expose_functions: true
+tools:
+  count_lines:
+    name: Count Lines
+    description: Count the lines in a file. Use this instead of reading a large file.
+    impl: primitive          # primitive | catalog | function
+    mutating: false
+    params:
+      - name: path
+        type: string
+        description: Path to the file, relative to the current directory.
+        required: true
+```
+
+`impl: primitive` dispatches to a callable in `agent/primitives.py` keyed by the tool key (adding
+a new one is a code change). `impl: catalog` and `impl: function` bridge to the tool registry and
+`functions.yaml` respectively via `target`, and need no code. `src/dev_setup/agent_tools.schema.json`
+documents every field for editor autocomplete; it is not enforced at runtime.
+
+### Session state
+
+- Prompt history: `~/.local/share/dev-setup/agent/history`
+- Transcripts: `~/.local/share/dev-setup/agent/transcripts/<timestamp>.json`, written after every
+  turn so a session that ends in a crash is still readable. `/history` shows the current session
+  and the transcript path.
+
+### Using the prompt
+
+- **Enter** sends. **Alt+Enter** (or **Ctrl-J**) inserts a newline, for pasting or writing
+  multi-line instructions.
+- **Type `/`** for a completion menu of session commands *and* every available tool, mutating
+  ones flagged with `!`. **Tab** cycles, **Enter** takes the highlighted entry.
+- `/<tool>` describes a tool and its parameters, e.g. `/write_file`. It does not run it — the
+  agent decides when tools run, so there is no back door around the confirmation flow.
+
+In-session commands: `/tools`, `/history`, `/cwd`, `/model`, `/reset`, `/help`, `/exit`.
+
+---
+
 ## Functions/Scripts
 
 Reusable shell functions/snippets, tracked in a separate catalog from installable tools
@@ -586,6 +740,21 @@ dev-setup-py/
         ├── functions_registry.py # Loads bundled + user YAML into the live function registry
         ├── function_runner.py    # Param resolution + script/eval/bashrc rendering & execution
         ├── functions.yaml        # Bundled built-in function catalog
+        ├── agent_tools.yaml       # Bundled agent tool catalog
+        ├── agent/                 # Local-model agent (see "Agent" above)
+        │   ├── config.py          # agent.yaml load/validate/save
+        │   ├── wizard.py          # first-run setup wizard (devstuff agent --setup)
+        │   ├── ollama.py          # stdlib-urllib client for /api/chat, /api/tags, /api/show
+        │   ├── preflight.py       # installed / reachable / pulled / tool-capable checks
+        │   ├── sandbox.py         # Workspace containment + command denylist + launch guard
+        │   ├── catalog.py         # agent_tools.yaml load/validate/merge
+        │   ├── registry.py        # AgentTool -> Ollama tool schema; function auto-exposure
+        │   ├── primitives.py      # _PRIMITIVES dispatch: read_file/write_file/list_dir/cd/run_command
+        │   ├── bridges.py         # catalog + functions.yaml bridges
+        │   ├── approval.py        # confirmation prompts, unified diffs
+        │   ├── loop.py            # tool-calling loop
+        │   ├── transcript.py      # per-session JSON transcript
+        │   └── session.py         # REPL, slash commands
         ├── ui.py          # Rich console helpers, questionary wrappers, styled prompts
         ├── commands/
         │   ├── list_cmd.py
@@ -596,7 +765,12 @@ dev-setup-py/
         │   ├── delete_cmd.py
         │   ├── catalog_cmd.py
         │   ├── run_cmd.py
-        │   └── functions_cmd.py
+        │   ├── functions_cmd.py
+        │   ├── skills_cmd.py
+        │   └── agent_cmd.py
+└── docs/
+    └── specs/             # Design docs per feature (see docs/specs/README.md)
+        └── agent/
 ```
 
 ### Adding a new built-in tool

{devstuff-1.15.0 → devstuff-1.16.0}/README.md

@@ -264,6 +264,160 @@ confirmation.
 
 ---
 
+## Agent
+
+`devstuff agent` opens an interactive session with a **local** model (via [Ollama](https://ollama.com))
+that can call devstuff's own tools plus a workspace-scoped filesystem/shell kit. Nothing leaves
+the machine, there are no API keys, and it works offline.
+
+```bash
+devstuff agent                                  # interactive REPL
+devstuff agent --setup                          # (re)run the configuration wizard
+devstuff agent --dir ~/projects                 # skip the workspace prompt
+devstuff agent --model granite4.1:8b            # override the configured model
+devstuff agent --print "which node tools do I have?"   # one-shot, non-interactive
+```
+
+```
+you ❯ create a python project called xyz-project with a hello world main.py
+
+  ↳ run_command(command='mkdir xyz-project')
+
+  ╭─ run in ./xyz-project ──────────────────────╮
+  │ mkdir xyz-project                           │
+  ╰─────────────────────────────────────────────╯
+  ? Run run_command?  Yes / No / Always allow this tool
+```
+
+### Setup
+
+First, make sure a tool-capable model is available:
+
+```bash
+devstuff install ollama
+ollama pull gemma4          # or any model reporting the `tools` capability
+```
+
+Then the **first time you run `devstuff agent`** with no configuration, a wizard walks you
+through it — Ollama host, then a pick-list of your locally available tool-capable models, then
+whether to show the model's reasoning. It writes `~/.config/dev-setup/agent.yaml` and continues
+into the session. Re-run it any time with `devstuff agent --setup`.
+
+The wizard only lists models that report the `tools` capability (`ollama show <model>` shows it
+under Capabilities), so you can't accidentally pick one that can't call tools. `devstuff agent`
+re-verifies this at startup regardless, and tells you which local models qualify if the
+configured one doesn't.
+
+The wizard is skipped when you pass `--model`/`--host` (you're already steering) or run
+non-interactively (`--print`), which fall back to built-in defaults.
+
+### Safety model
+
+The workspace root, chosen at launch (prompted, defaulting to the current directory), is the
+boundary:
+
+- **Path containment** — every path a tool touches is resolved (collapsing `..` and following
+  symlinks) and must land inside the workspace root. A symlink planted inside the workspace is
+  not a way out.
+- **Protected paths** — `~/.ssh`, `~/.aws`, `~/.gnupg` and `~/.config/gh` are refused for read
+  *and* write even if the workspace root contains them. `~/.config/dev-setup` is readable but
+  never writable: catalog authoring stays a human action.
+- **Confirmation** — every mutating tool call shows the exact command, or a unified diff for
+  `write_file`, and waits for yes / no / always-this-session. Read-only calls run silently.
+- **Denylist** — `sudo`, pipe-to-shell installers, catastrophic deletes, disk and service
+  commands, and redirects out of the workspace are refused before any prompt is shown, and are
+  **not** enabled by `--yolo`.
+- **Launch guard** — warns before handing the agent `$HOME`, a system directory, or a git repo
+  with uncommitted changes.
+
+`--yolo` skips confirmations for a session; the denylist and path containment still apply.
+In `--print` mode without `--yolo`, mutating calls are refused rather than auto-approved, so a
+scripted invocation cannot become an unattended agent with write access.
+
+### Configuration
+
+`~/.config/dev-setup/agent.yaml` (all fields optional):
+
+```yaml
+version: 1
+model: gemma4:latest
+host: http://localhost:11434     # a remote daemon works; the local binary is then not required
+temperature: 0.2
+num_ctx: 16384
+think: false                     # true renders the model's reasoning, dimmed
+max_iterations: 12               # tool calls per turn before the loop gives up
+request_timeout: 120
+command_timeout: 120
+max_tool_output_bytes: 8000      # tool output is truncated to this before going back to the model
+auto_approve: []                 # tool keys that never ask, e.g. ["write_file"]
+deny_patterns: []                # extra regexes refused on top of the built-in denylist
+```
+
+### Tools
+
+| Tool | Mutating | Purpose |
+|------|----------|---------|
+| `read_file` | | Read a UTF-8 file in the workspace |
+| `write_file` | ! | Create or overwrite a file (shows a diff) |
+| `list_dir` | | List a directory |
+| `cd` | | Move the working directory used by later calls |
+| `run_command` | ! | Run a shell command in the workspace |
+| `list_tools` | | List the devstuff catalog with install state |
+| `search_catalog` | | Find a catalog tool by name or description |
+| `tool_info` | | Details for one catalog tool |
+| `install_tool` | ! | Install a catalog tool (handles sudo itself) |
+| `fn_<key>` | ! | Every `type: script` entry in `functions.yaml`, exposed automatically |
+
+`cd` is a tool rather than a shell command because each `run_command` is its own subprocess — a
+shell `cd` would evaporate when it exits. `shell-eval` functions are deliberately excluded: they
+exist to mutate the calling shell, which a subprocess cannot do.
+
+### agent_tools.yaml
+
+The toolbox is a catalog, like everything else. Bundled at `src/dev_setup/agent_tools.yaml`,
+user overrides at `~/.config/dev-setup/agent_tools.yaml`, same merge precedence as `tools.yaml`.
+
+```yaml
+version: 1
+expose_functions: true
+tools:
+  count_lines:
+    name: Count Lines
+    description: Count the lines in a file. Use this instead of reading a large file.
+    impl: primitive          # primitive | catalog | function
+    mutating: false
+    params:
+      - name: path
+        type: string
+        description: Path to the file, relative to the current directory.
+        required: true
+```
+
+`impl: primitive` dispatches to a callable in `agent/primitives.py` keyed by the tool key (adding
+a new one is a code change). `impl: catalog` and `impl: function` bridge to the tool registry and
+`functions.yaml` respectively via `target`, and need no code. `src/dev_setup/agent_tools.schema.json`
+documents every field for editor autocomplete; it is not enforced at runtime.
+
+### Session state
+
+- Prompt history: `~/.local/share/dev-setup/agent/history`
+- Transcripts: `~/.local/share/dev-setup/agent/transcripts/<timestamp>.json`, written after every
+  turn so a session that ends in a crash is still readable. `/history` shows the current session
+  and the transcript path.
+
+### Using the prompt
+
+- **Enter** sends. **Alt+Enter** (or **Ctrl-J**) inserts a newline, for pasting or writing
+  multi-line instructions.
+- **Type `/`** for a completion menu of session commands *and* every available tool, mutating
+  ones flagged with `!`. **Tab** cycles, **Enter** takes the highlighted entry.
+- `/<tool>` describes a tool and its parameters, e.g. `/write_file`. It does not run it — the
+  agent decides when tools run, so there is no back door around the confirmation flow.
+
+In-session commands: `/tools`, `/history`, `/cwd`, `/model`, `/reset`, `/help`, `/exit`.
+
+---
+
 ## Functions/Scripts
 
 Reusable shell functions/snippets, tracked in a separate catalog from installable tools
@@ -559,6 +713,21 @@ dev-setup-py/
         ├── functions_registry.py # Loads bundled + user YAML into the live function registry
         ├── function_runner.py    # Param resolution + script/eval/bashrc rendering & execution
         ├── functions.yaml        # Bundled built-in function catalog
+        ├── agent_tools.yaml       # Bundled agent tool catalog
+        ├── agent/                 # Local-model agent (see "Agent" above)
+        │   ├── config.py          # agent.yaml load/validate/save
+        │   ├── wizard.py          # first-run setup wizard (devstuff agent --setup)
+        │   ├── ollama.py          # stdlib-urllib client for /api/chat, /api/tags, /api/show
+        │   ├── preflight.py       # installed / reachable / pulled / tool-capable checks
+        │   ├── sandbox.py         # Workspace containment + command denylist + launch guard
+        │   ├── catalog.py         # agent_tools.yaml load/validate/merge
+        │   ├── registry.py        # AgentTool -> Ollama tool schema; function auto-exposure
+        │   ├── primitives.py      # _PRIMITIVES dispatch: read_file/write_file/list_dir/cd/run_command
+        │   ├── bridges.py         # catalog + functions.yaml bridges
+        │   ├── approval.py        # confirmation prompts, unified diffs
+        │   ├── loop.py            # tool-calling loop
+        │   ├── transcript.py      # per-session JSON transcript
+        │   └── session.py         # REPL, slash commands
         ├── ui.py          # Rich console helpers, questionary wrappers, styled prompts
         ├── commands/
         │   ├── list_cmd.py
@@ -569,7 +738,12 @@ dev-setup-py/
         │   ├── delete_cmd.py
         │   ├── catalog_cmd.py
         │   ├── run_cmd.py
-        │   └── functions_cmd.py
+        │   ├── functions_cmd.py
+        │   ├── skills_cmd.py
+        │   └── agent_cmd.py
+└── docs/
+    └── specs/             # Design docs per feature (see docs/specs/README.md)
+        └── agent/
 ```
 
 ### Adding a new built-in tool

devstuff-1.16.0/dev/Makefile

@@ -0,0 +1,60 @@
+ROOT := ..
+
+# Pass TOOL=<key> to run-tests to test a single tool, e.g. make run-tests TOOL=uv
+# Pass PYTEST_ARGS="..." for arbitrary pytest flags, e.g. make run-tests PYTEST_ARGS="-x"
+TOOL     ?=
+PYTEST_ARGS ?=
+
+.PHONY: build build-ci run shell run-tests smoke-agent tui-tests clean
+
+# Build a fresh wheel from source, then build the Docker image.
+# Clean dist first so the glob in the Dockerfile matches exactly one file.
+build:
+	cd $(ROOT) && rm -f dist/*.whl dist/*.tar.gz && uv build
+	docker compose build
+
+# Build the CI image (sandbox + pytest + integration tests baked in)
+build-ci: build
+	docker build -f Dockerfile.ci -t dev-setup-ci ..
+
+# Drop into an interactive shell as the 'developer' user
+run: build
+	docker compose run --rm sandbox
+
+shell: run
+
+# Run the tool-install integration tests inside the CI container.
+# Scoped to test_tools.py on purpose: the agent suites are also integration-marked
+# but belong on the host (smoke-agent needs a daemon, tui-tests needs a PTY and
+# realistic timing), and neither has anything to do with installing tools.
+# Examples:
+#   make run-tests               — run every tool's install test
+#   make run-tests TOOL=uv       — run only the uv test
+#   make run-tests PYTEST_ARGS="-x --tb=long"
+run-tests: build-ci
+	$(eval _NODESEL := $(if $(TOOL),tests/integration/test_tools.py::test_install[$(TOOL)],tests/integration/test_tools.py))
+	docker run --rm dev-setup-ci \
+		pytest $(_NODESEL) -m integration -v --tb=short $(PYTEST_ARGS)
+
+# Smoke-test `devstuff agent` against a live Ollama daemon.
+# Runs on the HOST, not in Docker -- the CI image has no daemon, and yours may be
+# on another machine. Skips cleanly if nothing is reachable.
+#   make smoke-agent
+#   make smoke-agent AGENT_HOST=http://192.168.1.69:11434 AGENT_MODEL=gemma4:latest
+AGENT_HOST  ?=
+AGENT_MODEL ?=
+smoke-agent:
+	cd $(ROOT) && \
+	$(if $(AGENT_HOST),DEVSTUFF_AGENT_HOST=$(AGENT_HOST)) \
+	$(if $(AGENT_MODEL),DEVSTUFF_AGENT_MODEL=$(AGENT_MODEL)) \
+	uv run pytest tests/integration/test_agent_smoke.py -m integration -v $(PYTEST_ARGS)
+
+# Keystroke tests for the agent prompt, driven through a real PTY. Timing-dependent
+# and slow (~16s), so they are excluded from the default suite. No daemon needed.
+tui-tests:
+	cd $(ROOT) && uv run pytest tests/integration/test_agent_tui.py -m integration -v $(PYTEST_ARGS)
+
+# Remove the built images and named volume
+clean:
+	docker compose down --rmi local --volumes 2>/dev/null || true
+	docker rmi dev-setup-ci 2>/dev/null || true

devstuff-1.16.0/docs/specs/README.md

@@ -0,0 +1,41 @@
+# Specs
+
+Design documents for features and significant changes, one directory per feature.
+
+```
+docs/specs/
+└── <feature>/
+    ├── specifications.md    # what it does: numbered, testable requirements
+    ├── stack-decisions.md   # what we chose and what we rejected, with reasons
+    └── development-plan.md  # milestones, testing strategy, risks
+```
+
+## Why these exist
+
+Git history records *what changed*. These record *what was decided and why* — including the
+options that were rejected, which is the part that gets re-litigated eighteen months later when
+nobody remembers why the obvious approach wasn't taken.
+
+They are most useful when they capture:
+
+- **Rejected alternatives with their reasons.** "We didn't use the official Ollama package
+  because it pulls httpx + pydantic into every install" is worth more than the decision alone.
+- **Findings that changed the design.** A spec that still describes the original guess is worse
+  than no spec. When reality contradicts a requirement, update it and say when and why.
+- **Explicit non-goals.** Scope creep is easiest to resist against a written out-of-scope list.
+
+## Conventions
+
+- **Keep them current, or delete them.** A stale spec is actively misleading. If a document no
+  longer matches the code, fix it in the same PR that broke it.
+- **Mark resolved questions with a date and the answer**, rather than deleting the row — the fact
+  that something was once open is information.
+- **Requirements are numbered and testable** (FR-1, NFR-1) so tests and commits can cite them.
+- **Distinguish advisory behaviour from enforced behaviour.** Where a spec describes a security
+  property, say which mechanism is the control and which is merely a warning.
+
+## Existing specs
+
+| Feature | Status |
+|---------|--------|
+| [`agent/`](agent/) — `devstuff agent`, the local-model agent | Complete (v1) |