chore(release): 0.17.0 (#496)

anderskev · claude · web-flow · commit bd3a25f6b655 · 2026-02-22T23:25:55.000-05:00
* chore(release): bump version to 0.17.0

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

* docs: update VitePress site for v0.17.0 changes

- Rename working_dir → repo_root across configuration and data model docs
- Update driver references: "CLI driver" → "claude/codex drivers" throughout
- Fix Profile table in data-model.md to match actual fields (agents, sandbox, plan_path_pattern)
- Fix TrackerType "none" → "noop" to match code
- Add plan validation feedback loop to overview and roadmap
- Add ask_user_question interactive cards to roadmap
- Fix "YAML profiles" → "database-backed profiles" in landing page
- Add codex driver to troubleshooting credentials table
- Update copyright year to 2024-2026

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,9 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-02-22
+
+### Added
+
+- **pipeline:** Add plan validation feedback loop that automatically re-validates plans after architect revisions ([#493](https://github.com/existential-birds/amelia/pull/493))
+- **brainstorm:** Render `ask_user_question` tool calls as interactive cards in the dashboard ([#489](https://github.com/existential-birds/amelia/pull/489))
+- **drivers:** Add `CodexCliDriver` for OpenAI Codex CLI integration with subprocess-based NDJSON streaming ([#477](https://github.com/existential-birds/amelia/pull/477))
+
 ### Changed
 
-- **Breaking:** Replace legacy `cli` driver with explicit `claude` and `codex` drivers ([#473](https://github.com/existential-birds/amelia/issues/473))
+- **Breaking:** Replace legacy `cli` driver with explicit `claude` and `codex` drivers ([#477](https://github.com/existential-birds/amelia/pull/477))
 
   The generic `driver: "cli"` value has been split into explicit driver keys:
   - `claude` — wraps the Claude CLI binary
@@ -18,9 +26,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
   **Migration:** Update all profiles that use `driver: "cli"` to `driver: "claude"`. Legacy `cli` values are now rejected at startup. Recreate profiles with `amelia config profile create <name> --driver claude`.
 
-### Added
+- **Breaking:** Rename `Profile.working_dir` to `Profile.repo_root` for clarity ([#479](https://github.com/existential-birds/amelia/pull/479))
+
+  **Migration:** Update any code or configuration referencing `working_dir` to use `repo_root` instead. A database migration handles the column rename automatically.
+
+### Fixed
 
-- **drivers:** Add `CodexCliDriver` for OpenAI Codex CLI integration with subprocess-based NDJSON streaming
+- **architect:** Remove git commit step from plan template that caused unnecessary commit attempts during planning ([#494](https://github.com/existential-birds/amelia/pull/494))
+- **logging:** Replace todo table with styled Rich Panel widget to fix rendering issues ([#492](https://github.com/existential-birds/amelia/pull/492))
+- **dashboard:** Auto-focus input field when agent finishes responding for smoother interaction ([#491](https://github.com/existential-birds/amelia/pull/491))
+- **drivers:** Handle `rate_limit_event` and unknown SDK message types gracefully instead of crashing ([#475](https://github.com/existential-birds/amelia/pull/475))
+- **drivers:** Improve SDK stream handling robustness for edge cases ([#483](https://github.com/existential-birds/amelia/pull/483))
 
 ## [0.16.0] - 2026-02-18
 
diff --git a/amelia/__init__.py b/amelia/__init__.py
@@ -8,7 +8,7 @@
     __version__: Package version string.
 """
 
-__version__ = "0.16.0"
+__version__ = "0.17.0"
 
 __all__ = [
     "__version__",
diff --git a/dashboard/package.json b/dashboard/package.json
@@ -1,7 +1,7 @@
 {
   "name": "amelia-dashboard",
   "private": true,
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "Apache-2.0",
   "type": "module",
   "scripts": {
diff --git a/docs/site/.vitepress/config.ts b/docs/site/.vitepress/config.ts
@@ -95,7 +95,7 @@ export default defineConfig({
     // Footer
     footer: {
       message: 'Built by hey-amelia bot. Released under the <a href="https://github.com/existential-birds/amelia/blob/main/LICENSE">Apache License 2.0</a>.',
-      copyright: 'Copyright © 2024-2025 <a href="https://github.com/existential-birds">@existential-birds</a>'
+      copyright: 'Copyright © 2024-2026 <a href="https://github.com/existential-birds">@existential-birds</a>'
     },
 
     // Search configuration
diff --git a/docs/site/.vitepress/theme/components/CapabilitiesAndResearch.vue b/docs/site/.vitepress/theme/components/CapabilitiesAndResearch.vue
@@ -26,7 +26,7 @@ const items = [
   { capability: 'Swap drivers per agent', detail: 'Choose Claude Code CLI or API SDK per role. Implements SWE-agent\'s agent-computer interface principle.' },
   { capability: 'Resume from checkpoints', detail: 'Pick up failed workflows where they stopped. Uses Context Folding branch/return primitives.' },
   { capability: 'One model per role', detail: 'Assign different LLMs to Architect, Developer, and Reviewer. ReAct-style reasoning and acting per agent.' },
-  { capability: 'Configure via YAML profiles', detail: 'Prompts, tools, models, and context per profile. Stateless, immutable, append-only state design.' },
+  { capability: 'Configure via profiles', detail: 'Prompts, tools, models, and context per profile. Database-backed, immutable, append-only state design.' },
   { capability: 'Generate specs from issues', detail: 'Spec Builder turns GitHub/Linear issues into structured implementation plans.' },
   { capability: 'Watch it run in real time', detail: 'WebSocket-powered React dashboard shows agent progress as it happens.' },
 ]
diff --git a/docs/site/architecture/concepts.md b/docs/site/architecture/concepts.md
@@ -183,7 +183,7 @@ Developer marks execution complete
 
 ### Unified Streaming with StreamEvent
 
-Amelia uses a unified `StreamEvent` type for real-time streaming across all drivers. Regardless of whether you use the API driver or CLI driver, tool execution progress is communicated through the same event format.
+Amelia uses a unified `StreamEvent` type for real-time streaming across all drivers. Regardless of whether you use the API driver, Claude driver, or Codex driver, tool execution progress is communicated through the same event format.
 
 **StreamEventType** (the event categories):
 
@@ -209,7 +209,7 @@ Amelia uses a unified `StreamEvent` type for real-time streaming across all driv
 Each driver converts its native message types to `StreamEvent`:
 
 ```python
-# CLI driver converts SDK messages via convert_to_stream_event()
+# Claude CLI driver converts SDK messages via convert_to_stream_event()
 stream_event = convert_to_stream_event(sdk_message, agent="developer", workflow_id="...")
 
 # The UI and logging systems consume StreamEvent uniformly
@@ -222,7 +222,7 @@ This abstraction allows the dashboard and logging systems to display real-time p
 
 Drivers abstract how Amelia communicates with LLMs. This separation enables flexibility across different environments.
 
-### Why Two Drivers?
+### Why Multiple Drivers?
 
 | Driver | Use Case | Requirements |
 |--------|----------|--------------|
@@ -232,7 +232,7 @@ Drivers abstract how Amelia communicates with LLMs. This separation enables flex
 
 ### Driver Interface
 
-Both drivers implement a simple prompt-based interface:
+All drivers implement a simple prompt-based interface:
 
 ```python
 class DriverInterface(Protocol):
@@ -257,7 +257,7 @@ class DriverInterface(Protocol):
 
 ### Why This Matters
 
-Some environments prohibit direct API calls due to data retention policies. The CLI driver wraps existing approved tools (like `claude` CLI) that:
+Some environments prohibit direct API calls due to data retention policies. The CLI drivers wrap existing approved tools (`claude` and `codex` CLIs) that:
 - Inherit SSO authentication
 - Comply with data policies
 - Use existing security approvals
diff --git a/docs/site/architecture/data-model.md b/docs/site/architecture/data-model.md
@@ -12,7 +12,7 @@ This document describes the core data structures used throughout the Amelia orch
 | Type | Definition | Description |
 |------|------------|-------------|
 | `DriverType` | `"claude" \| "codex" \| "api"` | LLM driver type. |
-| `TrackerType` | `"jira" \| "github" \| "none"` | Issue tracker type. |
+| `TrackerType` | `"jira" \| "github" \| "noop"` | Issue tracker type. |
 | `AgenticStatus` | `"running" \| "awaiting_approval" \| "completed" \| "failed" \| "cancelled"` | Agentic execution status. |
 | `Severity` | `"low" \| "medium" \| "high" \| "critical"` | Review issue severity. |
 
@@ -37,14 +37,13 @@ Defines the runtime environment and constraints.
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `name` | `str` | — | Profile name (e.g., "work", "personal"). |
-| `driver` | `DriverType` | — | LLM driver type (e.g., "api", "claude", "codex"). |
-| `model` | `str \| None` | `None` | LLM model identifier. Required for API drivers (e.g., "minimax/minimax-m2"). |
-| `tracker` | `TrackerType` | `"none"` | Issue tracker type. |
-| `working_dir` | `str \| None` | `None` | Working directory for agentic execution. |
+| `tracker` | `TrackerType` | `"noop"` | Issue tracker type. |
+| `repo_root` | `str` | — | Root directory of the repository this profile targets. |
 | `plan_output_dir` | `str` | `"docs/plans"` | Directory for saving implementation plans. |
+| `plan_path_pattern` | `str` | `"docs/plans/{date}-{issue_key}.md"` | Path pattern for plan files with `{date}` and `{issue_key}` placeholders. |
 | `retry` | `RetryConfig` | `RetryConfig()` | Retry configuration for transient failures. |
-| `max_review_iterations` | `int` | `3` | Maximum review-fix loop iterations before terminating. |
-| `max_task_review_iterations` | `int` | `5` | Per-task review iteration limit for task-based execution. |
+| `agents` | `dict[str, AgentConfig]` | `{}` | Per-agent driver and model configuration. |
+| `sandbox` | `SandboxConfig` | `SandboxConfig()` | Sandbox execution configuration. |
 
 **Location:** `amelia/core/types.py`
 
@@ -240,7 +239,8 @@ class StreamEventType(StrEnum):
 Unified real-time streaming event from agent execution. This is the common message format across all drivers (CLI and API), enabling consistent UI rendering and logging regardless of the underlying LLM driver.
 
 Drivers convert their native message types to `StreamEvent` using conversion functions:
-- CLI driver: `convert_to_stream_event()` in `amelia/drivers/cli/claude.py`
+- Claude CLI driver: `convert_to_stream_event()` in `amelia/drivers/cli/claude.py`
+- Codex CLI driver: Conversion in `amelia/drivers/cli/codex.py`
 - API driver: Similar conversion in the API driver implementation
 
 | Field | Type | Default | Description |
diff --git a/docs/site/architecture/inspiration.md b/docs/site/architecture/inspiration.md
@@ -209,7 +209,7 @@ Production-grade patterns for building reliable agentic systems. Amelia's archit
 | MetaGPT SOP Roles | Architect → Developer ↔ Reviewer pipeline |
 | AgentCoder Iteration | Developer-Reviewer cycle until approval |
 | HULA Plan Approval | Human-in-the-loop approval gates |
-| SWE-agent ACI Design | Driver abstraction (`api` vs `cli`) |
+| SWE-agent ACI Design | Driver abstraction (`api` vs `claude` vs `codex`) |
 | LLM-as-a-Judge | Reviewer agent as automated code critic |
 | Reflexion Verbal RL | Review feedback as reinforcement signal |
 | ReAct Reasoning+Acting | Interleaved planning and tool execution |
diff --git a/docs/site/architecture/overview.md b/docs/site/architecture/overview.md
@@ -9,7 +9,7 @@ Technical deep dive into Amelia's architecture, components, and data flow.
 
 ## What Amelia Does Today
 
-**Phase 1 (Complete):** Multi-agent orchestration with the **Architect -> Developer -> Reviewer** loop. Issues flow through planning, execution, and review stages with human approval gates before any code ships. Supports both API-based (DeepAgents/LangChain) and CLI-based (Claude) LLM drivers, with Jira and GitHub issue tracker integrations.
+**Phase 1 (Complete):** Multi-agent orchestration with the **Architect -> Developer -> Reviewer** loop. Issues flow through planning, execution, and review stages with human approval gates before any code ships. Supports both API-based (DeepAgents/LangChain) and CLI-based (Claude, Codex) LLM drivers, with Jira and GitHub issue tracker integrations.
 
 ```
 Issue → [Queue] → Architect (plan) → Human Approval → Developer (execute) ↔ Reviewer (review) → Done
@@ -96,7 +96,7 @@ See [`amelia/pipelines/implementation/nodes.py`](https://github.com/existential-
 
 **Node: `call_architect_node`** - Gets driver, calls `Architect.plan()` to generate markdown plan with goal extraction, updates state with plan content.
 
-**Node: `plan_validator_node`** - Validates plan file and extracts structured fields (goal, plan_markdown, key_files) using lightweight LLM extraction.
+**Node: `plan_validator_node`** - Validates plan file and extracts structured fields (goal, plan_markdown, key_files) using lightweight LLM extraction. Runs in a feedback loop: if validation fails, the Architect revises the plan and re-validation occurs automatically.
 
 **Node: `human_approval_node`** - In server mode: emits `APPROVAL_REQUIRED` event and uses LangGraph interrupt to block. In CLI mode: prompts user directly via typer.
 
@@ -108,7 +108,7 @@ See [`amelia/pipelines/implementation/nodes.py`](https://github.com/existential-
 
 ### Why the Driver Abstraction?
 
-Some environments prohibit direct API calls due to data retention policies. The CLI driver wraps existing approved tools (like `claude` CLI) that inherit SSO authentication and comply with policies. Users can switch between API (fast prototyping) and CLI (policy compliance) without code changes.
+Some environments prohibit direct API calls due to data retention policies. The CLI drivers wrap existing approved tools (`claude` and `codex` CLIs) that inherit SSO authentication and comply with policies. Users can switch between API (fast prototyping) and CLI (policy compliance) without code changes.
 
 ### Why Separate Agents Instead of One Big Prompt?
 
diff --git a/docs/site/guide/configuration.md b/docs/site/guide/configuration.md
@@ -45,7 +45,7 @@ amelia config profile create my-profile \
   --driver api \
   --model "minimax/minimax-m2" \
   --tracker github \
-  --working-dir /path/to/project \
+  --repo-root /path/to/project \
   --activate
 ```
 
@@ -54,7 +54,7 @@ amelia config profile create my-profile \
 | `--driver` | `-d` | LLM driver (`claude`, `codex`, or `api`) |
 | `--model` | `-m` | Model name (required for API drivers) |
 | `--tracker` | `-t` | Issue tracker (`none`, `github`, `jira`) |
-| `--working-dir` | `-w` | Working directory for agent execution |
+| `--repo-root` | `-w` | Repository root path for agent execution |
 | `--activate` | `-a` | Set as active profile after creation |
 
 ### Activate Profile
@@ -94,7 +94,7 @@ Common models:
 - `google/gemini-2.5-flash` - Gemini 2.5 Flash (cost-effective)
 - `minimax/minimax-m2` - MiniMax M2
 
-For CLI drivers, model is optional but helps with clarity.
+For `claude` and `codex` drivers, model is optional but helps with clarity.
 
 ### Tracker
 
@@ -106,9 +106,9 @@ Where Amelia fetches issue details from.
 | `jira` | Jira issues | `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` env vars |
 | `none` | No tracker | None (use `--task` for ad-hoc tasks) |
 
-### Working Directory
+### Repository Root
 
-The directory where agents execute. When set, the Developer agent operates from this path.
+The root directory of the repository this profile targets. When set, the Developer agent operates from this path.
 
 Default: Current working directory where commands are run.
 
@@ -126,7 +126,7 @@ Default: `false`
 
 ## Per-Agent Configuration
 
-Each profile can configure individual agents with different drivers and models. This allows mixing CLI and API drivers within a single profile, or using different models for different agents.
+Each profile can configure individual agents with different drivers and models. This allows mixing `claude`, `codex`, and `api` drivers within a single profile, or using different models for different agents.
 
 View agent configurations:
 
@@ -230,8 +230,8 @@ The dashboard provides a visual interface for managing configuration at `/settin
 
 ### Profiles Tab
 
-- View all profiles as cards showing driver, agents, and working directory
-- Filter profiles by CLI or API driver type
+- View all profiles as cards showing driver, agents, and repository root
+- Filter profiles by driver type (`claude`, `codex`, or `api`)
 - Create new profiles with the "+ Create Profile" button
 - Click a profile card to edit its settings
 - Set active profile
@@ -250,7 +250,7 @@ amelia config profile create myproject \
   --driver api \
   --model "minimax/minimax-m2" \
   --tracker github \
-  --working-dir /path/to/myproject \
+  --repo-root /path/to/myproject \
   --activate
 
 # Verify the profile
diff --git a/docs/site/guide/troubleshooting.md b/docs/site/guide/troubleshooting.md
@@ -311,7 +311,7 @@ Plan file not found after architect completed
    amelia config profile activate dev-strong
    ```
 
-2. Or switch to the CLI driver (recommended for reliability):
+2. Or switch to the Claude driver (recommended for reliability):
    ```bash
    amelia config profile create dev-cli --driver claude
    amelia config profile activate dev-cli
@@ -408,7 +408,7 @@ Error: No profiles configured. Run 'amelia config profile create' to add one.
 
 1. Create a profile with CLI commands:
    ```bash
-   # Create a profile with CLI driver (recommended for getting started)
+   # Create a profile with Claude driver (recommended for getting started)
    amelia config profile create dev --driver claude --tracker none
 
    # Or with API driver
@@ -439,6 +439,7 @@ Error: OPENROUTER_API_KEY environment variable not set
 **Driver → Required Credentials:**
 - `api` → `OPENROUTER_API_KEY`
 - `claude` → Claude CLI authenticated (`claude auth login`)
+- `codex` → Codex CLI authenticated
 
 1. Set API key:
    ```bash
@@ -562,7 +563,7 @@ PathTraversalError: Path '../../../etc/passwd' resolves to '/etc/passwd' which i
 
 **Cause:** An agent tried to read or write a file outside the allowed directory (the worktree root).
 
-**What to do:** Agents are sandboxed to the working directory. If you need files outside the project, copy them into the worktree before starting the workflow.
+**What to do:** Agents are sandboxed to the repository root. If you need files outside the project, copy them into the worktree before starting the workflow.
 
 ---
 
diff --git a/docs/site/package.json b/docs/site/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@amelia/design-system-docs",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Amelia Design System documentation site built with VitePress by hey-amelia bot",
   "private": true,
   "type": "module",
diff --git a/docs/site/reference/roadmap.md b/docs/site/reference/roadmap.md
@@ -32,7 +32,7 @@ LangGraph state machine coordinating specialized agents with human approval gate
 
 - Agent orchestration (Architect → Developer → Reviewer loop)
 - Human approval gates before execution
-- Multi-driver support (API via OpenRouter, CLI via Claude)
+- Multi-driver support (API via OpenRouter, Claude CLI, Codex CLI)
 - GitHub and Jira issue tracker integrations (read-only)
 - Phased execution for Developer agent with per-task context isolation ([#188](https://github.com/existential-birds/amelia/issues/188))
 - Per-agent driver configuration ([#279](https://github.com/existential-birds/amelia/issues/279))
@@ -86,6 +86,13 @@ Document-assisted design tool for synthesizing specifications from research and
 - Handoff from brainstorming to implementation pipeline via `Design` state
 - Token usage and cost tracking per message
 - Tool execution visualization (tool calls, results, reasoning blocks)
+- Interactive `ask_user_question` cards for structured user input during brainstorming ([#489](https://github.com/existential-birds/amelia/pull/489))
+
+### Plan Validation
+
+Automated plan quality enforcement with feedback loops.
+
+- Plan validation feedback loop: automatic re-validation after architect revisions ([#493](https://github.com/existential-birds/amelia/pull/493))
 
 ### Parallel Execution Foundation
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "amelia"
-version = "0.16.0"
+version = "0.17.0"
 description = "A local agentic coding system with configurable profiles."
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "amelia-dashboard",`
`3`	`3`	`"private": true,`
`4`		`- "version": "0.16.0",`
	`4`	`+ "version": "0.17.0",`
`5`	`5`	`"license": "Apache-2.0",`
`6`	`6`	`"type": "module",`
`7`	`7`	`"scripts": {`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ const items = [`
`26`	`26`	`{ capability: 'Swap drivers per agent', detail: 'Choose Claude Code CLI or API SDK per role. Implements SWE-agent\'s agent-computer interface principle.' },`
`27`	`27`	`{ capability: 'Resume from checkpoints', detail: 'Pick up failed workflows where they stopped. Uses Context Folding branch/return primitives.' },`
`28`	`28`	`{ capability: 'One model per role', detail: 'Assign different LLMs to Architect, Developer, and Reviewer. ReAct-style reasoning and acting per agent.' },`
`29`		`- { capability: 'Configure via YAML profiles', detail: 'Prompts, tools, models, and context per profile. Stateless, immutable, append-only state design.' },`
	`29`	`+ { capability: 'Configure via profiles', detail: 'Prompts, tools, models, and context per profile. Database-backed, immutable, append-only state design.' },`
`30`	`30`	`{ capability: 'Generate specs from issues', detail: 'Spec Builder turns GitHub/Linear issues into structured implementation plans.' },`
`31`	`31`	`{ capability: 'Watch it run in real time', detail: 'WebSocket-powered React dashboard shows agent progress as it happens.' },`
`32`	`32`	`]`