amatelier 0.3.0__tar.gz

amatelier-0.3.0/.cursor/rules/amatelier.mdc

@@ -0,0 +1,96 @@
+---
+description: amatelier repository rules (Amatayo Standard)
+globs: ["**/*"]
+alwaysApply: true
+---
+
+# Amatelier — Claude Code Instructions
+
+Instructions for working on this repository inside Claude Code.
+
+## What this project is
+
+A self-evolving multi-model AI team skill for Claude Code
+
+## Repo layout
+
+- `src/amatelier/` — shipped package (the canonical code)
+- `tests/` — mirrors `src/` structure
+- `examples/first_run/` — zero-config runnable demo
+- `docs/` — human documentation (MkDocs, Diataxis tiers)
+- `llm/` — LLM-facing documentation (flat, exhaustive, machine-readable)
+- `scripts/` — shell and one-off utility scripts
+- `.github/workflows/` — CI, publish, release, docs workflows
+
+## Rules
+
+1. **Amatayo Standard.** This repo follows the Amatayo Standard. Structure is enforced by CI.
+2. **Dual-docs invariant.** Every change that adds a public symbol, CLI flag, or config key must update `llm/SPEC.md` and the relevant `docs/reference/*` file. The `llm/API.md` and `llm/SCHEMA.md` files are generated — don't hand-edit them.
+3. **`llm/` is flat.** Never create subdirectories in `llm/`. Flat is the invariant.
+4. **Tests required.** New code requires new tests. `make test` must pass before PR.
+5. **Conventional commits.** `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`. Releases are driven by commit history.
+6. **No secrets.** `.env.example` documents variables; real values never committed.
+
+## Two-layer paths (critical)
+
+Amatelier is pip-installable; the bundled package must stay read-only at runtime. Two layers exist:
+
+- **Bundled layer** — `src/amatelier/` and any files shipped inside the wheel. This is the canonical source. Runtime code MUST NOT write here.
+- **User data layer** — everything returned by `amatelier.paths.user_data_dir()` and its siblings (`user_agent_dir`, `user_db_path`, `user_digest_dir`, `user_briefing_dir`, `user_store_ledger`, `user_novel_concepts`, `user_shared_skills_index`, `user_config_override`). All mutable state goes here.
+
+Rules for AI agents editing this repo:
+
+- Any code that persists state, writes logs, updates ledgers, or mutates agent memory must route through a `paths.user_*()` helper. Do not hard-code paths under `src/amatelier/` for writes.
+- Persona seed files (per-agent `CLAUDE.md`, `IDENTITY.md` under `src/amatelier/agents/<name>/`) are bundled. Edits to seeds only affect a user's environment after `amatelier refresh-seeds` or a fresh install.
+- Generated files must not be hand-edited: `llm/API.md`, `llm/SCHEMA.md`, `llms.txt`, `llms-full.txt`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`. CI regenerates them.
+
+## Three LLM backend modes
+
+All LLM calls must go through `amatelier.llm_backend.get_backend()`. The backend abstraction resolves to one of three modes at runtime:
+
+| Mode | Selected when | Backend class |
+|---|---|---|
+| `claude-code` | Running inside Claude Code, `claude` binary on PATH | `ClaudeCLIBackend` |
+| `anthropic-sdk` | `ANTHROPIC_API_KEY` present, no Claude Code session | `AnthropicSDKBackend` |
+| `openai-compat` | `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, or local Ollama | `OpenAICompatBackend` |
+
+Override with `AMATELIER_MODE=claude-code|anthropic-sdk|openai-compat`.
+
+When introducing new LLM calls:
+
+- Call `get_backend()` and use the returned object's interface. Do not shell out to the `claude` CLI directly and do not `import anthropic` at the call site.
+- Any new backend capability must be added to the `LLMBackend` Protocol in `src/amatelier/llm_backend.py` and implemented by all three concrete backends.
+- Surface new provider env vars in `describe_environment()` so `amatelier config` reports them.
+
+## Tests
+
+- `tests/test_smoke.py` — pytest suite, import/CLI smoke checks, runs in CI
+- `tests/test_refresh_seeds.py` — pytest suite, verifies seed materialization, runs in CI
+- `tests/test_integration.py` — **standalone script**, exercises live LLM backends, NOT pytest and NOT run in CI. Execute manually when verifying backend changes.
+
+Run the CI-equivalent suites locally:
+
+```bash
+pytest tests/test_smoke.py -v
+pytest tests/test_refresh_seeds.py -v
+```
+
+## Common commands
+
+```bash
+make setup        # install package + dev deps
+make test         # run test suite
+make lint         # ruff + mypy
+make demo         # run examples/first_run/
+make docs         # build docs site locally
+amatelier config          # show active mode, credentials, paths
+amatelier refresh-seeds   # rematerialize per-agent seeds in user data dir
+```
+
+## When editing docs
+
+Use the `dual-docs-architect` skill. It classifies every write (tutorial / guide / reference / explanation x human / LLM / both) and routes to the correct file.
+
+## When scaffolding new repos
+
+Use the `repo-architect` skill. Don't copy this file by hand — let the skill render it.

amatelier-0.3.0/.depth/backend-delegation_gate.md

@@ -0,0 +1,26 @@
+TASK: delegate remaining subprocess claude calls to llm_backend
+SCOPE: non-trivial
+FILES: src/amatelier/engine/classify_concepts.py, src/amatelier/engine/backfill_distill.py, src/amatelier/engine/roundtable_runner.py, src/amatelier/engine/therapist.py, src/amatelier/engine/steward_dispatch.py
+REPLACES: 6 direct subprocess.run(["claude", ...]) call sites that hardcode the Claude CLI — broken for users without `claude` on PATH even when ANTHROPIC_API_KEY is set
+MIGRATION: none — each site keeps its existing subprocess call as the claude-code-mode fallback; only adds a backend-first check for open-mode users
+CALLERS:
+- classify_concepts._call_sonnet_classifier() — batch concept classification
+- backfill_distill._distill_skills_sonnet() — retroactive skill extraction from old digests
+- roundtable_runner._summarize_round_haiku() — per-round summaries via haiku
+- roundtable_runner._distill_skills() — post-RT skill extraction via sonnet (called from run_roundtable)
+- therapist._call_llm(prompt, model) — shared helper for _call_therapist, _call_gemini (gemini via its own path)
+- steward_dispatch.run_steward_subagent() — tool-using research agent (cannot delegate — requires agent spawning)
+USER_PATH: amatelier roundtable → roundtable_runner.run_roundtable() → [Round N] → _summarize_round_haiku() | → [post-RT] _distill_skills() | → classify_concepts() | → therapist() | → steward tagged requests → each site calls backend.complete() when backend.name != "claude-code", else falls through to existing subprocess.run(["claude", ...])
+RED_STATE: 6 sites in engine/ directly call subprocess.run(["claude", "-p", "--model", ...]). User in anthropic-sdk or openai-compat mode hits FileNotFoundError('claude') at every site after Judge scoring succeeds (since Judge is the only site already delegating).
+RED_TYPE: USER-OBSERVABLE
+GREEN_CONDITION:
+- When AMATELIER_MODE=anthropic-sdk (or auto-detected via ANTHROPIC_API_KEY with no claude binary): all 5 simple sites (classify_concepts, backfill_distill, 2 roundtable_runner sites, therapist) succeed via Anthropic SDK. Steward returns a degradation message explaining claude-code requirement.
+- When claude-code mode: all sites continue using their existing subprocess.run() path with zero observable difference (same flags, same timeouts, same error handling).
+- pytest tests/test_smoke.py passes (13/13)
+- pytest tests/test_db_integration.py passes (11/11)
+- ruff check src/ passes on the edited files
+OMISSIONS:
+- steward_dispatch in non-claude-code mode returns {"status": "unavailable", "result": "Steward requires claude-code mode..."} instead of spawning a tool-using agent. Proper tool-use delegation (Anthropic SDK messages API with tools param) is out of scope — multi-hour refactor.
+- No new tests added; existing smoke + integration tests cover the non-delegation path. Live verification of open-mode requires ANTHROPIC_API_KEY in CI, which is a separate secrets/keys task.
+- gemini_client and naomi (Naomi worker) unchanged — already use their own google-genai path
+- engine/claude_agent.py line 264 — NOT in scope (this is the legacy shim; newer sites should use llm_backend.call_claude instead, but claude_agent.py still works for back-compat and is out of scope)

amatelier-0.3.0/.depth/current_task.txt

@@ -0,0 +1 @@
+openmode-fixes-v1

amatelier-0.3.0/.depth/manual-ci-local_gate.md

@@ -0,0 +1,14 @@
+TASK: manual CI — replace auto-trigger with local script
+SCOPE: routine
+FILES: scripts/ci_local.py (new), Makefile (ci target), .github/workflows/ci.yml, .github/workflows/wheel-smoke.yml, .github/workflows/docs.yml
+REPLACES: auto-triggered workflows that burn GitHub Actions minutes on every push/PR — replaced by local script + workflow_dispatch manual-only triggers
+MIGRATION: none — existing v* tag triggers preserved on all workflows (release/publish paths unchanged)
+CALLERS: developer runs `python scripts/ci_local.py` or `make ci` before pushing. CI workflows callable from Actions UI via workflow_dispatch when needed.
+USER_PATH: developer makes code change → runs `python scripts/ci_local.py` locally → script runs ruff + pytest smoke + mkdocs + wheel build + DB integration test sequentially → exits 0 on success, 1 with failure list on failure → developer pushes only if green
+RED_STATE: ci.yml/wheel-smoke.yml/docs.yml all had `on: push: branches: [main]` and `pull_request: branches: [main]` — every push/PR triggered ~7min of CI runs per commit. No cross-platform local CI script existed; Makefile targets unusable on Windows without `make`.
+RED_TYPE: INFRASTRUCTURE
+GREEN_CONDITION: `python scripts/ci_local.py` runs all 5 checks (ruff, pytest smoke, mkdocs, wheel build, pytest integration) on any OS with Python, reports pass/fail per check, exits non-zero on any failure. Pushing to main does NOT fire ci.yml/wheel-smoke.yml/docs.yml. Pushing a `v*` tag DOES fire all of them plus publish.yml + release.yml.
+OMISSIONS:
+- No Docker / `act` integration — users wanting true CI parity can still run `docker compose run --rm integration` as before
+- scripts/ci_local.py does not support parallel execution — runs checks sequentially (acceptable for <10s per check)
+- Makefile `ci` target delegates to python script; mac/linux users could bypass this but it's simpler to maintain one implementation

amatelier-0.3.0/.depth/openmode-fixes-v1_gate.md

@@ -0,0 +1,34 @@
+TASK: apply Open-mode RT fixes (text accumulation, exception guard, response_format)
+SCOPE: non-trivial
+FILES: src/amatelier/llm_backend.py, src/amatelier/engine/judge_scorer.py, src/amatelier/engine/classify_concepts.py, src/amatelier/engine/backfill_distill.py, src/amatelier/engine/roundtable_runner.py
+REPLACES:
+  1. AnthropicSDKBackend.complete_with_tools at llm_backend.py:319-321 `final_text = "".join(text_chunks)` — only captures the LAST iteration's text. All intermediate-turn narration is discarded when the model stops calling tools.
+  2. AnthropicSDKBackend.complete_with_tools at llm_backend.py:298 `msg = client.messages.create(...)` — no try/except. SDK RateLimitError / APIError / network failures crash the loop with the partial `messages` state inaccessible to callers for retry.
+  3. OpenAICompatBackend.complete at llm_backend.py:~305 `client.chat.completions.create(...)` — no `response_format`. GPT-4o and most OpenAI-compat models often emit markdown-fenced JSON or conversational filler when engine prompts require strict JSON (judge scoring, skill classification, skill distillation). Causes JSON parse crash for first openai-compat user.
+MIGRATION: None — all three fixes are additive or strictly-more-robust behavior. Existing claude-code and anthropic-sdk callers see no behavior change. openai-compat callers now get valid JSON where engine prompts request it; callers that pass text prompts continue to work (json_mode defaults to False).
+CALLERS:
+  - complete_with_tools: only called from steward_dispatch.spawn_steward_subagent() — this is the Steward tool-use path in anthropic-sdk mode.
+  - complete (with new json_mode kwarg): called from 5 engine sites currently, 4 of which request JSON-shaped output (judge_scorer, classify_concepts, backfill_distill, roundtable_runner._distill_skills). Haiku summarizer + therapist call it for text, no json_mode change needed.
+USER_PATH:
+  Fix 1: user in anthropic-sdk mode runs amatelier roundtable with [[request: ...]] tags → Steward invokes complete_with_tools → model narrates "Let me check X" in iteration 1, calls read_file, synthesizes "Based on X, the answer is Y" in iteration 2 → BEFORE: only "Based on X..." returned. AFTER: both iterations' text concatenated.
+  Fix 2: user in anthropic-sdk mode hits a transient 429 rate-limit during iteration 3 of a Steward loop → BEFORE: RateLimitError propagates unhandled, partial message state lost, Steward returns status=error. AFTER: exception caught, accumulated messages visible in log, tool_use_id round-trip preserved, Steward returns status=error with full diagnostic context.
+  Fix 3: user with OPENAI_API_KEY or OPENROUTER_API_KEY set, runs first roundtable → judge_scorer._call_sonnet() calls backend.complete(..., json_mode=True) → OpenAICompatBackend adds response_format={"type":"json_object"} → GPT-4o returns clean JSON → engine parses successfully. BEFORE: GPT-4o returns `` ```json\n{...}\n``` ``, parser crashes with JSONDecodeError.
+RED_STATE:
+  - llm_backend.py:320 `final_text = "".join(text_chunks)` — text_chunks is the current iteration's blocks only; prior iterations' text already discarded at the top of each loop iteration
+  - llm_backend.py:298-305 client.messages.create is not inside a try/except; only the tool_executor call later in the loop is protected
+  - llm_backend.py:~305 OpenAICompatBackend.complete client.chat.completions.create has no response_format param and no json_mode detection
+  - judge_scorer.py:~155 backend.complete(system=..., prompt=..., model="sonnet", max_tokens=8000, timeout=360, effort=effort) — passes no json_mode; JSON-requiring prompt hits openai-compat without response_format
+  - classify_concepts.py, backfill_distill.py, roundtable_runner.py:_distill_skills: same pattern — backend.complete without json_mode, all 3 request JSON output
+RED_TYPE: USER-OBSERVABLE
+GREEN_CONDITION:
+  1. complete_with_tools accumulates text from all iterations (final_text = existing_text + "".join(current_chunks)) — unit test: mock 3 iterations, assert iteration-2 text in returned Completion.text
+  2. complete_with_tools wraps the `msg = client.messages.create(...)` call in try/except; on exception, returns a Completion with text=accumulated_text_so_far, model, backend, latency_ms, and logs a warning with the accumulated messages length
+  3. LLMBackend.complete accepts optional `json_mode: bool = False`. OpenAICompatBackend translates json_mode=True → response_format={"type":"json_object"}. ClaudeCLIBackend and AnthropicSDKBackend accept and ignore (Claude handles JSON without hint).
+  4. Four engine call sites pass json_mode=True where they expect JSON: judge_scorer._call_sonnet, classify_concepts._call_sonnet_classifier, backfill_distill.distill_one, roundtable_runner._distill_skills
+  5. Local CI passes: ruff, pytest smoke 13/13, pytest integration 11/11, mkdocs build
+OMISSIONS:
+  - Marcus's 5 mock tests are NOT added in this commit. They're good engineering but not ship-blockers; add in a follow-up commit (tests/test_llm_backend.py).
+  - Extended-thinking cost/quality assertion remains uncovered (requires live key; documented as known gap in tests/README.md follow-up).
+  - roundtable_runner._summarize_round_haiku and therapist._call_llm pass text prompts — no json_mode change, intentionally left at default False.
+  - gemini_agent uses its own path, unchanged.
+  - The RT infrastructure collapse (14 worker timeouts in rounds 2-3) is not addressed by these code fixes — it's a concurrency/rate-limit product behavior to document separately, not a code bug.

amatelier-0.3.0/.depth/security-mitigations-v1_gate.md

@@ -0,0 +1,33 @@
+TASK: apply Security RT v2 mandatory mitigations (#2, #3, #4)
+SCOPE: critical
+FILES: src/amatelier/engine/steward_tools.py, src/amatelier/engine/steward_dispatch.py, src/amatelier/cli.py, src/amatelier/paths.py
+REPLACES: three security holes confirmed by Security RT digest-afd96c74180e and Elena's Grand Insight ("path containment and sensitive-file access are orthogonal concerns, and only the first is defended"):
+  1. steward_tools.read_file() has no credential denylist — agents can request `.env`, `.git/config`, `~/.aws/credentials` and they pass _safe_resolve() because they're inside WORKSPACE_ROOT
+  2. steward_dispatch.format_result() returns full result text and runner persists it to digest + steward-log JSON — credentials read once exfiltrate to durable artifacts
+  3. spawn_steward_subagent() executes on first dispatch with no user consent moment — GDPR Article 13 requires disclosure before processing event, not at install time
+MIGRATION: Existing CI/automation that runs amatelier roundtables must set AMATELIER_STEWARD_CONSENT=1 to skip the runtime prompt; documented in CHANGELOG and .env.example.
+CALLERS:
+  - steward_tools.read_file() — called from dispatch_tool() during anthropic-sdk Steward tool-use loop
+  - steward_dispatch.format_result() — called from runner research-window phase
+  - steward_dispatch.spawn_steward_subagent() — called from runner research-window + per-round dispatch
+  - cli.py existing roundtable subcommand — gains pre-flight consent check
+USER_PATH: developer runs `amatelier roundtable` → CLI checks AMATELIER_STEWARD_CONSENT env or prior accept → if neither, prints disclosure + prompts for y/n → on consent, sets process env var for child processes → runner enters research window → agents emit `[[request: read .env]]` → steward dispatch resolves to read_file('.env') → _is_secret_path(p) returns True → returns "Error: blocked secret-path .env (Steward denylist)" → result truncated to 4KB at format_result + persisted truncated to digest → no credential ever transits to Anthropic API or persists to disk artifact
+RED_STATE:
+  - steward_tools.py:140-152 read_file() opens any path that passes _safe_resolve(). No filename or extension check.
+  - steward_dispatch.py:419-422 format_result() returns the full result['result'] string for runner injection.
+  - roundtable_runner.py around line 590 db_cmd("speak", "runner", inject_msg) writes full text to messages table → digest persistence.
+  - StewardLog.record() at steward_dispatch.py around line 440 writes full result to steward-log JSON.
+  - cli.py roundtable command spawns runner immediately on invocation. No consent moment.
+RED_TYPE: USER-OBSERVABLE (privacy + security harm to end users)
+GREEN_CONDITION:
+  - steward_tools._is_secret_path(p) blocks: `.env`, `.env.*`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `id_rsa`, `id_ed25519`, `credentials`, `.git/config`, `.aws/credentials`, `.netrc`, `.npmrc`, `.pypirc`, anything ending in `_token` or `_secret` or `_key` (case-insensitive). read_file() and grep() return "Error: blocked secret-path..." string instead of content.
+  - format_result() truncates the result text at 4096 chars before injection, prepending a `[truncated to 4KB]` marker if needed.
+  - StewardLog.record() truncates the persisted result text at 4096 chars.
+  - First spawn_steward_subagent() call per amatelier process checks env AMATELIER_STEWARD_CONSENT in {"1","yes","true"}; if missing, raises SteWardConsentRequired with a documented message; cli.py catches the exception, prompts the user with a clear disclosure (sends file content excerpts to claude/anthropic API), and sets AMATELIER_STEWARD_CONSENT=1 for the current process if user accepts.
+  - All four checks have unit-test-style verification by directly invoking _is_secret_path() with a fixture list, calling format_result() with oversize string, and calling spawn_steward_subagent() with the env var unset.
+OMISSIONS:
+  - The denylist is filename-pattern based, not content-scanned. A user-renamed credential file (e.g. mysecret.txt) is not blocked — documented as known limitation.
+  - The truncation length is hardcoded 4096; not yet exposed in config.json. A future RT can tune.
+  - Consent is per-process not persistent — restarting amatelier re-prompts. Persistent consent (a checkbox in user_data_dir) deferred.
+  - Steward in claude-code mode (subprocess CLI) gets the truncation but not the read_file denylist — denylist runs in the SDK tool-use path only. CLI mode uses the actual claude binary's Read tool which has its own surface. This is documented as deferred — claude-code Steward limitation.
+  - openai-compat backend already returns "unavailable" for Steward; mitigations don't apply there.

amatelier-0.3.0/.depth/steward-tool-use_gate.md

@@ -0,0 +1,27 @@
+TASK: implement Steward tool use in anthropic-sdk mode
+SCOPE: non-trivial
+FILES: src/amatelier/engine/steward_tools.py (new), src/amatelier/llm_backend.py, src/amatelier/engine/steward_dispatch.py
+REPLACES: steward_dispatch.py returns {"status": "unavailable"} in open mode — degrades Steward empirical grounding. Implement actual Anthropic SDK tool-use loop (messages API with tools= param) backed by local read_file/grep/glob functions sandboxed to WORKSPACE_ROOT.
+MIGRATION: none — claude-code mode path unchanged; anthropic-sdk now succeeds with real lookups instead of returning degradation message; openai-compat still degrades (tool schemas differ across OAI-compat providers, out of scope)
+CALLERS:
+- steward_dispatch.spawn_steward_subagent() at line ~253 — called from roundtable_runner when agents emit [[request: ...]] tags
+- AnthropicSDKBackend.complete_with_tools() (new method) — called only from steward_dispatch, not wired into LLMBackend Protocol (avoids forcing all backends to implement)
+- steward_tools.dispatch_tool(name, input) — internal router called by the tool-use loop
+USER_PATH: amatelier roundtable (ANTHROPIC_API_KEY set, no claude CLI) → worker emits "[[request: show schema of messages table]]" → runner detects request → steward_dispatch.spawn_steward_subagent() → backend.name == "anthropic-sdk" → call complete_with_tools(system=STEWARD_SYSTEM_PROMPT, user=request, tools=STEWARD_TOOL_SPECS) → Anthropic returns tool_use block for grep/read_file → steward_tools.dispatch_tool() executes locally with path validation → result appended as tool_result → loop until model returns text → return {"status": "success", "result": text} to runner
+RED_STATE: steward_dispatch.py:291-310 returns {"status": "unavailable"} when backend.name != "claude-code". In anthropic-sdk mode, [[request]] tags produce degradation messages instead of real data.
+RED_TYPE: USER-OBSERVABLE
+GREEN_CONDITION:
+- steward_tools.py exports STEWARD_TOOL_SPECS (3 tools: read_file, grep, glob) and dispatch_tool(name, input) -> str
+- steward_tools._safe_resolve() rejects path-traversal attempts (absolute paths outside WORKSPACE_ROOT, ../../etc)
+- AnthropicSDKBackend has a new method complete_with_tools(system, user, tools, max_iterations=10) that loops tool_use → tool_result until final text
+- steward_dispatch in anthropic-sdk mode returns real data, same structure as claude-code: {"status": "success", "result": str, "elapsed_s": float}
+- Existing claude-code path unchanged (byte-identical flags + subprocess call)
+- openai-compat continues to return {"status": "unavailable"} — documented in OMISSIONS
+- pytest tests/test_smoke.py passes (13/13), pytest tests/test_db_integration.py passes (11/11)
+- ruff clean on new files
+OMISSIONS:
+- OpenAI-compat tool use NOT implemented. OpenAI and OpenRouter support tools but schemas differ (OpenAI functions vs Anthropic tools). A cross-provider abstraction would double the code for marginal benefit since OAI-compat Steward usage is niche. Users who need Steward in OAI-compat must set AMATELIER_MODE=anthropic-sdk with ANTHROPIC_API_KEY.
+- Tool sandbox is path-based only — no syscall sandboxing. Steward can read any file under WORKSPACE_ROOT including .env, secrets, etc. Same security posture as claude-code mode (Read tool with --dangerously-skip-permissions).
+- No timeout per tool call (only overall complete_with_tools timeout). A single grep on a huge directory could block.
+- No token accounting across tool-use iterations — follows existing judge_scorer pattern.
+- No new tests; existing smoke + integration tests cover non-steward paths. Live verification requires ANTHROPIC_API_KEY which is a separate concern.

amatelier-0.3.0/.depth/wire-judge-max-effort_gate.md

@@ -0,0 +1,15 @@
+TASK: wire judge max-effort via extended thinking
+SCOPE: non-trivial
+FILES: src/amatelier/llm_backend.py, src/amatelier/engine/judge_scorer.py
+REPLACES: AnthropicSDKBackend.complete() at llm_backend.py:207 currently ignores thinking; _call_sonnet() at judge_scorer.py:144 passes max_tokens=8000 with no thinking budget; config.json has "effort": "max" under judge but code ignores it
+MIGRATION: none — new optional `effort` param on LLMBackend.complete() defaults to None, preserves all existing call sites
+CALLERS: judge_scorer._call_sonnet() will pass effort=<config.judge.effort> to backend.complete(). All other callers (call_claude shim at llm_backend.py:427, other engine sites) continue passing no effort and get identical behavior to today.
+USER_PATH: amatelier roundtable → engine/roundtable_runner.py triggers scoring phase → engine/judge_scorer.py:score_contributions() → _call_sonnet(prompt) → reads config.judge.effort via _get_judge_effort() → backend.complete(effort="max") → AnthropicSDKBackend.complete() adds thinking={"type":"enabled","budget_tokens":16000} to client.messages.create() → Anthropic API returns with extended reasoning → higher-quality scoring
+RED_STATE: llm_backend.py:219 `client.messages.create(model=, max_tokens=, system=, messages=, timeout=)` — no thinking kwarg. judge_scorer.py:156-159 `backend.complete(system="", prompt=prompt, model="sonnet", max_tokens=8000, timeout=360)` — no effort param exists. config.json line 37 `"effort": "max"` reads but never flows to API call.
+RED_TYPE: INFRASTRUCTURE
+GREEN_CONDITION: When config.judge.effort == "max" AND backend.name == "anthropic-sdk", the Anthropic messages.create() call receives thinking={"type": "enabled", "budget_tokens": 16000} and max_tokens is bumped to ≥20000. Other backends (claude-code, openai-compat) accept the effort kwarg without erroring and ignore it (log debug). judge_scorer continues to work when config has no effort field (effort=None, no thinking block).
+OMISSIONS:
+- OpenAICompatBackend.complete() at llm_backend.py:284 has no extended-thinking equivalent; OpenRouter/OpenAI users ignore effort (platform-level limitation)
+- Only judge reads effort from config; agent LLM calls at engine/roundtable_runner.py do not propagate effort (out of scope)
+- budget_tokens is hardcoded to 16000 for effort="max"; not exposed as config.judge.budget_tokens (follow-up)
+- No new tests added; tests/test_smoke.py already covers backend.complete() without effort and will continue to pass

amatelier-0.3.0/.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "name": "amatelier dev",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.10",
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/common-utils:2": {}
+  },
+  "postCreateCommand": "pip install -e \".[dev]\"",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "charliermarsh.ruff",
+        "ms-python.mypy-type-checker"
+      ],
+      "settings": {
+        "python.testing.pytestEnabled": true,
+        "python.testing.pytestArgs": ["tests"]
+      }
+    }
+  }
+}

amatelier-0.3.0/.env.example

@@ -0,0 +1,17 @@
+# Required for the Gemini Flash agent (Naomi)
+# Get your key at: https://aistudio.google.com/apikey
+GEMINI_API_KEY=your-gemini-api-key-here
+
+# Optional — override workspace root when the skill is not installed at
+# the default .claude/skills/claude-suite layout. Rarely needed.
+# AMATELIER_WORKSPACE=/absolute/path/to/project
+
+# Optional — enables proposal queueing into an external evolution harness
+# (therapist.py). Leave unset to run standalone.
+# CLAUDE_EVOLUTION_HARNESS=/absolute/path/to/harness/repo
+
+# Required for non-interactive / CI use of `amatelier roundtable`.
+# Confirms you understand the Steward subagent reads files from
+# AMATELIER_WORKSPACE and sends excerpts to the configured LLM provider.
+# Interactive users will be prompted on first dispatch instead.
+# AMATELIER_STEWARD_CONSENT=1

amatelier-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+A clear, concise description.
+
+## To reproduce
+
+1. Step one
+2. Step two
+3. See error
+
+## Expected behavior
+
+What should have happened.
+
+## Environment
+
+- OS:
+- Version of this package:
+- Python/Node version:
+- How installed (pip / npm / source):
+
+## Logs / traceback
+
+```
+paste here
+```
+
+## Additional context
+
+Anything else relevant.

amatelier-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest a new capability or improvement
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+What problem does this solve? Who has this problem?
+
+## Proposed solution
+
+Describe what you'd like to happen.
+
+## Alternatives considered
+
+Other approaches you've thought about.
+
+## Additional context
+
+Screenshots, links to similar features elsewhere, etc.

amatelier-0.3.0/.github/copilot-instructions.md

@@ -0,0 +1,92 @@
+# GitHub Copilot Instructions — amatelier
+
+_This file is generated from CLAUDE.md. Do not hand-edit._
+
+Instructions for working on this repository inside Claude Code.
+
+## What this project is
+
+A self-evolving multi-model AI team skill for Claude Code
+
+## Repo layout
+
+- `src/amatelier/` — shipped package (the canonical code)
+- `tests/` — mirrors `src/` structure
+- `examples/first_run/` — zero-config runnable demo
+- `docs/` — human documentation (MkDocs, Diataxis tiers)
+- `llm/` — LLM-facing documentation (flat, exhaustive, machine-readable)
+- `scripts/` — shell and one-off utility scripts
+- `.github/workflows/` — CI, publish, release, docs workflows
+
+## Rules
+
+1. **Amatayo Standard.** This repo follows the Amatayo Standard. Structure is enforced by CI.
+2. **Dual-docs invariant.** Every change that adds a public symbol, CLI flag, or config key must update `llm/SPEC.md` and the relevant `docs/reference/*` file. The `llm/API.md` and `llm/SCHEMA.md` files are generated — don't hand-edit them.
+3. **`llm/` is flat.** Never create subdirectories in `llm/`. Flat is the invariant.
+4. **Tests required.** New code requires new tests. `make test` must pass before PR.
+5. **Conventional commits.** `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`. Releases are driven by commit history.
+6. **No secrets.** `.env.example` documents variables; real values never committed.
+
+## Two-layer paths (critical)
+
+Amatelier is pip-installable; the bundled package must stay read-only at runtime. Two layers exist:
+
+- **Bundled layer** — `src/amatelier/` and any files shipped inside the wheel. This is the canonical source. Runtime code MUST NOT write here.
+- **User data layer** — everything returned by `amatelier.paths.user_data_dir()` and its siblings (`user_agent_dir`, `user_db_path`, `user_digest_dir`, `user_briefing_dir`, `user_store_ledger`, `user_novel_concepts`, `user_shared_skills_index`, `user_config_override`). All mutable state goes here.
+
+Rules for AI agents editing this repo:
+
+- Any code that persists state, writes logs, updates ledgers, or mutates agent memory must route through a `paths.user_*()` helper. Do not hard-code paths under `src/amatelier/` for writes.
+- Persona seed files (per-agent `CLAUDE.md`, `IDENTITY.md` under `src/amatelier/agents/<name>/`) are bundled. Edits to seeds only affect a user's environment after `amatelier refresh-seeds` or a fresh install.
+- Generated files must not be hand-edited: `llm/API.md`, `llm/SCHEMA.md`, `llms.txt`, `llms-full.txt`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`. CI regenerates them.
+
+## Three LLM backend modes
+
+All LLM calls must go through `amatelier.llm_backend.get_backend()`. The backend abstraction resolves to one of three modes at runtime:
+
+| Mode | Selected when | Backend class |
+|---|---|---|
+| `claude-code` | Running inside Claude Code, `claude` binary on PATH | `ClaudeCLIBackend` |
+| `anthropic-sdk` | `ANTHROPIC_API_KEY` present, no Claude Code session | `AnthropicSDKBackend` |
+| `openai-compat` | `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, or local Ollama | `OpenAICompatBackend` |
+
+Override with `AMATELIER_MODE=claude-code|anthropic-sdk|openai-compat`.
+
+When introducing new LLM calls:
+
+- Call `get_backend()` and use the returned object's interface. Do not shell out to the `claude` CLI directly and do not `import anthropic` at the call site.
+- Any new backend capability must be added to the `LLMBackend` Protocol in `src/amatelier/llm_backend.py` and implemented by all three concrete backends.
+- Surface new provider env vars in `describe_environment()` so `amatelier config` reports them.
+
+## Tests
+
+- `tests/test_smoke.py` — pytest suite, import/CLI smoke checks, runs in CI
+- `tests/test_refresh_seeds.py` — pytest suite, verifies seed materialization, runs in CI
+- `tests/test_integration.py` — **standalone script**, exercises live LLM backends, NOT pytest and NOT run in CI. Execute manually when verifying backend changes.
+
+Run the CI-equivalent suites locally:
+
+```bash
+pytest tests/test_smoke.py -v
+pytest tests/test_refresh_seeds.py -v
+```
+
+## Common commands
+
+```bash
+make setup        # install package + dev deps
+make test         # run test suite
+make lint         # ruff + mypy
+make demo         # run examples/first_run/
+make docs         # build docs site locally
+amatelier config          # show active mode, credentials, paths
+amatelier refresh-seeds   # rematerialize per-agent seeds in user data dir
+```
+
+## When editing docs
+
+Use the `dual-docs-architect` skill. It classifies every write (tutorial / guide / reference / explanation x human / LLM / both) and routes to the correct file.
+
+## When scaffolding new repos
+
+Use the `repo-architect` skill. Don't copy this file by hand — let the skill render it.

amatelier-0.3.0/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

amatelier-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+# Matrix policy: every push/PR runs the fast path (ubuntu + Python 3.12 only).
+# Full matrix (3 OSes x 4 Pythons) runs on v* tags so release validation stays
+# thorough without burning minutes on every commit.
+
+on:
+  # Manual-only: run `make ci` locally before pushing. Fires on v* tags
+  # for release validation, and can be triggered via the Actions UI.
+  workflow_dispatch:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Full matrix on release tags; fast path otherwise.
+        os: ${{ startsWith(github.ref, 'refs/tags/v') && fromJSON('["ubuntu-latest", "macos-latest", "windows-latest"]') || fromJSON('["ubuntu-latest"]') }}
+        python-version: ${{ startsWith(github.ref, 'refs/tags/v') && fromJSON('["3.10", "3.11", "3.12", "3.13"]') || fromJSON('["3.12"]') }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Type check (Linux/macOS only — Windows mypy trips on system dirs)
+        if: runner.os != 'Windows'
+        run: |
+          mypy --no-strict-optional \
+            src/amatelier/__init__.py \
+            src/amatelier/cli.py \
+            src/amatelier/paths.py \
+            src/amatelier/llm_backend.py || true
+      - name: Test (pytest smoke suite — no live APIs)
+        run: pytest tests/test_smoke.py -v
+
+  build-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - run: pip install dist/*.whl

amatelier-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,70 @@
+# Builds the human docs site (MkDocs Material) and regenerates LLM-facing
+# derivatives on every push to main. Also runs on PRs as a dry-build to catch
+# doc errors before merge.
+
+name: Docs
+
+on:
+  # Manual-only: run `mkdocs build` locally to verify. Trigger via Actions UI
+  # when you want to publish the docs site. Fires on v* tags for releases.
+  workflow_dispatch:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install MkDocs + plugins
+        run: |
+          pip install \
+            mkdocs-material \
+            mkdocs-awesome-pages-plugin \
+            pymdown-extensions
+
+      - name: Build MkDocs site
+        run: mkdocs build --strict
+
+      # dual-docs-architect provides a regenerate script at scripts/regen_llm.py
+      # It reads src/, docs/, examples/ and writes llm/API.md, llm/SCHEMA.md,
+      # llms.txt, llms-full.txt, .cursor/rules/*, .github/copilot-instructions.md.
+      # If the script doesn't exist yet, this step is a no-op.
+      - name: Regenerate LLM surface
+        run: |
+          if [ -f scripts/regen_llm.py ]; then
+            python scripts/regen_llm.py
+          else
+            echo "scripts/regen_llm.py not present yet — skipping regeneration"
+          fi
+
+      - name: Check for unsynced derivatives
+        if: github.event_name == 'pull_request'
+        run: |
+          if ! git diff --exit-code; then
+            echo "::error::Generated files are out of sync. Run 'make docs' locally and commit."
+            exit 1
+          fi
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site