@agile-vibe-coding/avc 0.3.4 → 0.4.0

package/README.md

@@ -384,25 +384,95 @@ The Seed button appears on story cards in the kanban board detail modal. It runs
 
 ### Run (Kanban Run Button)
 
-Implements a task's code in an isolated git worktree using AI agents, runs tests, and merges to the main branch on success.
+Implements a task's code in an isolated git worktree using an **agentic tool-calling loop** — the same pattern used by Claude Code, OpenAI Codex, and Cursor. The AI agent iteratively reads existing code, writes files, runs tests, and fixes failures until all acceptance criteria pass. The worktree then moves to human review before merging.
+
+#### Agentic Tool-Calling Loop
+
+The Run ceremony follows the **Claude Code architecture**: a single-threaded loop where the model calls tools until it decides to stop. There is no fixed sequence — the model itself is the orchestrator.
+
+```
+while (model produces tool calls):
+    execute each tool call in the worktree sandbox
+    feed results back to model
+    model decides next action (or stops)
+```
+
+The loop ends when the model returns a text response with no tool calls — the same stop condition as Claude Code. A safety bound of 50 iterations prevents runaway loops.
+
+#### Available Tools
+
+The agent has 7 tools, all sandboxed to the worktree directory (paths outside the worktree are rejected):
+
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `read_file(path)` | Read existing code | Inspect imports, patterns, structure before writing |
+| `write_file(path, content)` | Create or overwrite files | Write new source files and tests |
+| `edit_file(path, old, new)` | Targeted search-and-replace | Fix a specific function without rewriting the whole file |
+| `delete_file(path)` | Remove files | Clean up obsolete code |
+| `list_files(pattern?)` | Explore project structure | `list_files("src/**/*.js")` to see existing code |
+| `run_command(cmd)` | Execute shell commands | `npm test`, `npm install`, `npx tsc` |
+| `search_code(pattern, glob?)` | Search for patterns in code | Find function definitions, import usages |
+
+#### Typical Agent Workflow
+
+The agent follows an explore-implement-test-fix cycle:
+
+```
+Agent: list_files("**/*")                     # explore project structure
+Agent: read_file("src/index.html")            # understand existing code
+Agent: read_file("package.json")              # check test setup
+Agent: write_file("src/calculator.js", code)  # implement the feature
+Agent: write_file("test/calculator.test.js", tests)  # write tests
+Agent: run_command("npm test")                # run tests
+  -> "FAIL: expected 8 but got NaN"
+Agent: read_file("src/calculator.js")         # inspect the failure
+Agent: edit_file("src/calculator.js",         # targeted fix
+        "parseInt(a)", "Number(a)")
+Agent: run_command("npm test")                # re-run
+  -> "PASS: 5 tests passed"
+Agent: "Done. All 5 tests pass."              # stops (no more tool calls)
+```
 
 #### Worktree Lifecycle
 
-1. **Pre-flight check** — verifies package.json and git repo exist.
-2. **Create worktree** — `git worktree add .avc/worktrees/{taskId} -b avc/{taskId}` creates an isolated branch.
-3. **Read documentation chain** — walks the full hierarchy (project -> epic -> story -> task -> subtasks), concatenating all `doc.md` and `context.md` files into a single context string.
-4. **Code generation** (LLM, [`code-implementer.md`](src/cli/agents/code-implementer.md)) — generates source files and tests following traceability rules: hierarchy-prefixed naming, JSDoc provenance headers, functional purity, domain vocabulary.
-5. **Code validation** (LLM, [`code-validator.md`](src/cli/agents/code-validator.md)) — verifies generated code against check definitions in [`src/cli/checks/code/`](src/cli/checks/code/). If violations found, feeds them back to the implementer (up to 3 iterations).
-6. **Run tests** — executes the project's test command in the worktree. If tests fail, the worktree is cleaned up and the task is marked `failed`.
-7. **Commit and merge** — stages all changes, commits, merges to main with `--no-ff`, then cleans up the worktree and branch.
+1. **Pre-flight check** — verifies git repo exists.
+2. **Create worktree** — `git worktree add .avc/worktrees/{taskId} -b avc/{taskId}`. Excludes `.avc/`, `node_modules/`, and `.env` from the worktree.
+3. **Read documentation chain** — concatenates all `doc.md` and `context.md` files from project -> epic -> story -> task into a single context string.
+4. **Agentic loop** — the agent receives the doc chain, acceptance criteria, and tools. It implements the code iteratively until all tests pass.
+5. **Commit in worktree** — stages and commits all changes. Does NOT merge to main.
+6. **Move to Review** — task status becomes `implemented` (Review column). The worktree stays on disk for human inspection.
+
+#### Human Review
+
+After the agent completes, the task appears in the **Review** column on the kanban board. The reviewer can:
+
+- Inspect the code: `cd .avc/worktrees/{taskId}`
+- Run tests: `npm test`
+- Review the diff: `git log --oneline -1 && git diff HEAD~1`
+- **Approve** — move to `completed` (automatically merges the branch to main and cleans up the worktree)
+- **Reject** — move to `failed` (can retry with Run button)
 
-#### Function Registry
+#### Comparison with Other AI Coding Tools
 
-After implementation, the task's `work.json` receives a `functions` array listing every generated function with its file path, type, purity flag, line count, and which acceptance criterion it satisfies. This registry propagates upward — stories aggregate from tasks, epics from stories. The kanban board displays it under a "Code" tab.
+AVC's Run ceremony follows the same core architecture as industry-leading AI coding tools, adapted for structured project contexts:
+
+| Aspect | AVC Run | Claude Code | OpenAI Codex | Cursor |
+|--------|---------|------------|-------------|--------|
+| **Loop pattern** | Tool-calling loop, model stops when done | Same | Same | Same (ReAct) |
+| **# of tools** | 7 (scoped to worktree) | 25+ (general purpose) | 5 + MCP | 10+ |
+| **Sandbox** | Git worktree (disposable) | Permission system | OS-native (Bubblewrap) | Custom infra |
+| **Context** | Pre-scoped doc chain (project->task) | CLAUDE.md + exploration | AGENTS.md + exploration | Trained embeddings |
+| **Test handling** | Agent runs tests via `run_command`, reads failures, fixes iteratively | Same pattern | Same pattern | Same pattern |
+| **Review** | Human review gate before merge | Immediate (user decides) | Immediate | Immediate |
+| **Subagents** | No (tasks are small by design) | Yes (depth-limited) | Yes (Guardian) | Yes (8 parallel) |
+
+**Key difference**: AVC provides pre-scoped context via the hierarchical documentation chain (project -> epic -> story -> task `context.md` + `doc.md`), so the agent doesn't need to explore the codebase from scratch. Claude Code and Codex must discover project structure themselves via tool calls. This makes AVC's loop shorter and cheaper — typically 10-20 tool calls vs 30-50 for a comparable task in Claude Code.
+
+**Why fewer tools**: AVC's agent implements one atomic task (2-5 acceptance criteria) in an isolated worktree. It doesn't need web search (docs are in the context chain), task management (handled by work.json), user questions (specs are complete from Seed/Sprint Planning), or subagents (tasks are small enough for one context window).
 
 #### Configuration
 
-The Run ceremony is configured in `.avc/avc.json` with per-stage model selection (`code-generation`, `code-validation`), `maxValidationIterations`, and `acceptanceThreshold`. Code check definitions in `src/cli/checks/code/` are customizable via the kanban Settings -> Agents tab.
+The Run ceremony is configured in `.avc/avc.json` with per-stage model selection (`code-generation`, `code-validation`). Code check definitions in `src/cli/checks/code/` are customizable via the kanban Settings -> Agents tab.
 
 ### Kanban Board (`/kanban`)
 
@@ -465,7 +535,7 @@ AVC uses a **single prompt strategy** where agent instructions and task data are
 
 ## Code Generation Rules
 
-AVC enforces coding rules on AI-generated code to ensure full traceability from requirements to implementation. These rules are enforced by check definitions in [`src/cli/checks/code/`](src/cli/checks/code/) and validated by the code-validator agent during the Run ceremony.
+AVC enforces coding rules on AI-generated code to ensure full traceability from requirements to implementation. These rules are embedded in the [`code-implementer.md`](src/cli/agents/code-implementer.md) agent prompt (which the model follows during the agentic loop) and validated by check definitions in [`src/cli/checks/code/`](src/cli/checks/code/).
 
 ### Hierarchy-Prefixed Naming
 
@@ -507,3 +577,7 @@ Function names use vocabulary from the documentation chain — domain nouns and
 4. **LLM Limitations Research** — [arXiv:2410.12972](https://arxiv.org/html/2410.12972v2) — 40-80% performance drops when combining knowledge and instruction-following in separate channels.
 
 5. **Hierarchical Documentation Strategy** — Gloaguen et al. (2025) — [arXiv:2602.11988](https://arxiv.org/abs/2602.11988) — Comprehensive context files reduce agent task-success rates by 20%+.
+
+6. **Claude Code Agent Architecture** — [How Claude Code Works](https://code.claude.com/docs/en/how-claude-code-works) — Single-threaded tool-calling loop where the model is the orchestrator. AVC's Run ceremony follows this same pattern.
+
+7. **OpenAI Codex Agent Loop** — [Unrolling the Codex Agent Loop](https://openai.com/index/unrolling-the-codex-agent-loop/) — Tool-calling loop with sandboxed execution, same core architecture as Claude Code and AVC.

package/cli/agents/code-implementer.md

@@ -1,53 +1,39 @@
 # Code Implementer Agent
 
-You are an expert software engineer generating production-quality code from a fully specified task. Your output must satisfy all acceptance criteria and follow strict traceability and quality rules.
+You are an expert software engineer implementing a task in an isolated git worktree. You have tools to read, write, and edit files, run shell commands, and search code. Work iteratively — read existing code, write your implementation, run tests, and fix issues until all acceptance criteria pass.
 
-## Your Task
+## Available Tools
 
-Given a task's documentation chain (project → epic → story → task → subtasks), generate all source files and test files needed to implement the task.
+You have these tools. Use them as needed — there is no fixed order:
 
-## Input Format
+- **read_file(path)** — Read a file's contents. Use to inspect existing code, imports, patterns.
+- **write_file(path, content)** — Create or overwrite a file. Use for new source files and tests.
+- **edit_file(path, old_string, new_string)** — Replace a specific string in a file. Use for targeted changes to existing files. The old_string must be unique and match exactly.
+- **delete_file(path)** — Delete a file. Use to remove obsolete or incorrect files.
+- **list_files(pattern?)** — List files matching a glob pattern. Use to explore the project structure.
+- **run_command(command)** — Execute a shell command. Use for `npm test`, `npm install`, `npx tsc`, etc.
+- **search_code(pattern, glob?)** — Search for a regex pattern in files. Use to find function definitions, imports, usages.
+
+## Workflow
+
+Follow this pattern, but adapt as needed:
+
+1. **Explore** — Start by listing existing files and reading key files to understand the project structure, conventions, and existing code.
+2. **Plan** — Based on the acceptance criteria and existing code, decide what files to create/edit and what functions to write.
+3. **Implement** — Write source files following all coding rules below. Write test files that cover every acceptance criterion.
+4. **Test** — Run the project's test command (typically `npm test`). Read the output.
+5. **Fix** — If tests fail, read the error output, inspect the relevant code, and fix the issue. Repeat until tests pass.
+6. **Verify** — Once tests pass, review your implementation to ensure all ACs are covered and all coding rules are followed.
+
+When all tests pass and all acceptance criteria are satisfied, stop calling tools. Your final text response should be a brief summary of what was implemented.
+
+## Input
 
 You receive:
 - `## Hierarchy Prefix` — the naming prefix for this task (e.g., `e0001_s0002_t0003`)
 - `## Task ID` — the full task ID (e.g., `context-0001-0002-0003`)
 - `## Acceptance Criteria` — numbered list of ACs from work.json
 - `## Documentation Chain` — concatenated doc.md + context.md from project through task
-- `## Coding Rules Summary` — the rules your code must follow
-
-## Output Format
-
-Return ONLY valid JSON:
-
-```json
-{
-  "files": [
-    {
-      "path": "src/domain/e0001-s0002-t0003-function-name.js",
-      "content": "full file content with provenance header and JSDoc",
-      "functions": ["e0001_s0002_t0003_functionName"]
-    }
-  ],
-  "tests": [
-    {
-      "path": "src/domain/e0001-s0002-t0003-function-name.test.js",
-      "content": "full test file content",
-      "acceptanceCriteria": ["context-0001-0002-0003#AC1"]
-    }
-  ],
-  "functionRegistry": [
-    {
-      "name": "e0001_s0002_t0003_functionName",
-      "file": "src/domain/e0001-s0002-t0003-function-name.js",
-      "type": "exported",
-      "pure": true,
-      "satisfies": "context-0001-0002-0003#AC1",
-      "lines": 18
-    }
-  ],
-  "summary": "Brief description of what was implemented"
-}
-```
 
 ## Coding Rules
 
@@ -90,7 +76,6 @@ Every exported function has:
 ### 5. Functional Purity
 - Business logic functions must be pure (same input → same output, no side effects)
 - Side effects (file I/O, API calls, database) go in separate boundary functions
-- Mark pure functions with `pure: true` in the function registry
 
 ### 6. Domain Naming
 - Use nouns and verbs from the documentation chain
@@ -109,9 +94,11 @@ Every exported function has:
 
 ## Important Rules
 
-1. **Generate complete files** — not diffs, not patches, not pseudocode
-2. **Include all imports** — every file must be self-contained and runnable
-3. **Follow the tech stack** from the project documentation exactly
-4. **Implement ONLY what the task requires** — no extra features, no premature abstractions
-5. **Every function must trace to an AC** — no orphan code
-6. **Use the exact hierarchy prefix provided** — do not invent your own
+1. **Start by exploring** — Always read existing files before writing. Understand the project structure, existing patterns, and imports.
+2. **Follow the tech stack** from the project documentation exactly — do not introduce new frameworks or libraries unless the documentation specifies them.
+3. **Implement ONLY what the task requires** — no extra features, no premature abstractions.
+4. **Every function must trace to an AC** — no orphan code.
+5. **Use the exact hierarchy prefix provided** — do not invent your own.
+6. **Run tests after writing code** — do not stop without verifying.
+7. **Fix test failures** — read the error, find the bug, fix it, re-run. Do not give up after one failure.
+8. **When done, stop calling tools** — just return a text summary of what you implemented.

package/cli/init.js

@@ -957,11 +957,12 @@ class ProjectInitiator {
     // Items to add to gitignore
     const itemsToIgnore = [
       { pattern: '.env', comment: 'Environment variables' },
-      { pattern: '.avc/documentation/.vitepress/dist', comment: 'VitePress build output' },
-      { pattern: '.avc/documentation/.vitepress/cache', comment: 'VitePress cache' },
       { pattern: '.avc/logs', comment: 'Command execution logs' },
       { pattern: '.avc/token-history.json', comment: 'Token usage tracking' },
-      { pattern: '.avc/ceremonies-history.json', comment: 'Ceremony execution history' }
+      { pattern: '.avc/ceremonies-history.json', comment: 'Ceremony execution history' },
+      { pattern: '.avc/worktrees', comment: 'AVC worktrees (generated code branches)' },
+      { pattern: '.avc/documentation/.vitepress/dist', comment: 'VitePress build output' },
+      { pattern: '.avc/documentation/.vitepress/cache', comment: 'VitePress cache' },
     ];
 
     let newContent = gitignoreContent;

package/cli/llm-claude.js

@@ -173,4 +173,76 @@ export class ClaudeProvider extends LLMProvider {
     });
     return text;
   }
+
+  /**
+   * Multi-turn conversation with tool calling for the agentic loop.
+   * Uses Anthropic's messages API with tool_use/tool_result content blocks.
+   */
+  async chat(messages, options = {}) {
+    if (!this._client) this._client = this._createClient();
+
+    const maxTokens = options.maxTokens || getMaxTokensForModel(this.model);
+
+    // Convert unified message format to Anthropic format
+    const anthropicMessages = [];
+    for (const msg of messages) {
+      if (msg.role === 'system') continue; // handled via system param
+      if (msg.role === 'tool') {
+        // Tool results go as user messages with tool_result content blocks
+        anthropicMessages.push({
+          role: 'user',
+          content: [{ type: 'tool_result', tool_use_id: msg.toolCallId, content: msg.content }],
+        });
+      } else if (msg.role === 'assistant' && msg.toolCalls?.length > 0) {
+        // Assistant messages with tool calls become tool_use content blocks
+        const content = [];
+        if (msg.content) content.push({ type: 'text', text: msg.content });
+        for (const tc of msg.toolCalls) {
+          content.push({ type: 'tool_use', id: tc.id, name: tc.name, input: tc.arguments });
+        }
+        anthropicMessages.push({ role: 'assistant', content });
+      } else {
+        anthropicMessages.push({ role: msg.role, content: msg.content });
+      }
+    }
+
+    // Convert tools from OpenAI format to Anthropic format
+    const anthropicTools = (options.tools || []).map(t => ({
+      name: t.function.name,
+      description: t.function.description,
+      input_schema: t.function.parameters,
+    }));
+
+    const params = {
+      model: this.model,
+      max_tokens: maxTokens,
+      messages: anthropicMessages,
+    };
+    if (anthropicTools.length > 0) params.tools = anthropicTools;
+    const systemMsg = messages.find(m => m.role === 'system');
+    if (systemMsg) params.system = systemMsg.content;
+    if (options.system) params.system = options.system;
+
+    const response = await this._withRetry(
+      () => this._client.messages.create(params),
+      'Chat (Claude)'
+    );
+    this._trackTokens(response.usage);
+
+    // Extract text and tool calls from response content blocks
+    let textContent = '';
+    const toolCalls = [];
+    for (const block of response.content) {
+      if (block.type === 'text') textContent += block.text;
+      if (block.type === 'tool_use') {
+        toolCalls.push({ id: block.id, name: block.name, arguments: block.input });
+      }
+    }
+
+    return {
+      content: textContent,
+      toolCalls,
+      stopReason: response.stop_reason, // 'end_turn' | 'tool_use'
+    };
+  }
 }

package/cli/llm-gemini.js

@@ -136,4 +136,80 @@ export class GeminiProvider extends LLMProvider {
     });
     return text;
   }
+
+  /**
+   * Multi-turn conversation with tool calling for the agentic loop.
+   * Uses Gemini's generateContent with functionDeclarations.
+   */
+  async chat(messages, options = {}) {
+    if (!this._client) this._client = this._createClient();
+
+    // Convert messages to Gemini format
+    const contents = [];
+    for (const msg of messages) {
+      if (msg.role === 'system') continue;
+      if (msg.role === 'tool') {
+        contents.push({
+          role: 'function',
+          parts: [{ functionResponse: { name: msg.toolName || 'tool', response: { result: msg.content } } }],
+        });
+      } else if (msg.role === 'assistant' && msg.toolCalls?.length > 0) {
+        const parts = [];
+        if (msg.content) parts.push({ text: msg.content });
+        for (const tc of msg.toolCalls) {
+          parts.push({ functionCall: { name: tc.name, args: tc.arguments } });
+        }
+        contents.push({ role: 'model', parts });
+      } else {
+        contents.push({ role: msg.role === 'assistant' ? 'model' : 'user', parts: [{ text: msg.content }] });
+      }
+    }
+
+    // Convert tools from OpenAI format to Gemini format
+    const geminiTools = (options.tools || []).length > 0
+      ? [{ functionDeclarations: options.tools.map(t => ({
+          name: t.function.name,
+          description: t.function.description,
+          parameters: t.function.parameters,
+        })) }]
+      : undefined;
+
+    const params = {
+      model: this.model,
+      contents,
+    };
+    const config = {};
+    const systemMsg = messages.find(m => m.role === 'system');
+    if (systemMsg || options.system) config.systemInstruction = systemMsg?.content || options.system;
+    if (geminiTools) config.tools = geminiTools;
+    if (Object.keys(config).length > 0) params.config = config;
+
+    const response = await this._withRetry(
+      () => this._client.models.generateContent(params),
+      'Chat (Gemini)'
+    );
+    this._trackTokens(response.usageMetadata);
+
+    // Extract text and function calls from response
+    let textContent = '';
+    const toolCalls = [];
+    const parts = response.candidates?.[0]?.content?.parts || [];
+    for (const part of parts) {
+      if (part.text) textContent += part.text;
+      if (part.functionCall) {
+        toolCalls.push({
+          id: `gemini-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+          name: part.functionCall.name,
+          arguments: part.functionCall.args || {},
+        });
+      }
+    }
+
+    const finishReason = response.candidates?.[0]?.finishReason || 'STOP';
+    return {
+      content: textContent,
+      toolCalls,
+      stopReason: finishReason, // 'STOP' | 'TOOL_CALLS'
+    };
+  }
 }

package/cli/llm-local.js

@@ -490,4 +490,56 @@ export class LocalProvider extends LLMProvider {
     });
     return textContent;
   }
+
+  /**
+   * Multi-turn conversation with tool calling (OpenAI-compatible API).
+   * Local models have variable tool-calling support — falls back gracefully.
+   */
+  async chat(messages, options = {}) {
+    if (!this._client) this._client = this._createClient();
+
+    const openaiMessages = messages.map(msg => {
+      if (msg.role === 'tool') {
+        return { role: 'tool', tool_call_id: msg.toolCallId, content: msg.content };
+      }
+      if (msg.role === 'assistant' && msg.toolCalls?.length > 0) {
+        return {
+          role: 'assistant',
+          content: msg.content || null,
+          tool_calls: msg.toolCalls.map(tc => ({
+            id: tc.id,
+            type: 'function',
+            function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+          })),
+        };
+      }
+      return { role: msg.role, content: msg.content };
+    });
+
+    const params = {
+      model: this.model,
+      messages: openaiMessages,
+    };
+    if (options.tools?.length > 0) params.tools = options.tools;
+    if (options.maxTokens) params.max_tokens = options.maxTokens;
+
+    const response = await this._withRetry(
+      () => this._client.chat.completions.create(params),
+      'Chat (Local)'
+    );
+    this._trackTokens(response.usage);
+
+    const choice = response.choices[0];
+    const toolCalls = (choice.message.tool_calls || []).map(tc => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: typeof tc.function.arguments === 'string' ? JSON.parse(tc.function.arguments) : tc.function.arguments,
+    }));
+
+    return {
+      content: choice.message.content || '',
+      toolCalls,
+      stopReason: choice.finish_reason,
+    };
+  }
 }

package/cli/llm-openai.js

@@ -451,4 +451,56 @@ export class OpenAIProvider extends LLMProvider {
       return textContent;
     }
   }
+
+  /**
+   * Multi-turn conversation with tool calling for the agentic loop.
+   * Uses OpenAI's chat.completions API with function calling.
+   */
+  async chat(messages, options = {}) {
+    if (!this._client) this._client = this._createClient();
+
+    const openaiMessages = messages.map(msg => {
+      if (msg.role === 'tool') {
+        return { role: 'tool', tool_call_id: msg.toolCallId, content: msg.content };
+      }
+      if (msg.role === 'assistant' && msg.toolCalls?.length > 0) {
+        return {
+          role: 'assistant',
+          content: msg.content || null,
+          tool_calls: msg.toolCalls.map(tc => ({
+            id: tc.id,
+            type: 'function',
+            function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+          })),
+        };
+      }
+      return { role: msg.role, content: msg.content };
+    });
+
+    const params = {
+      model: this.model,
+      messages: openaiMessages,
+    };
+    if (options.tools?.length > 0) params.tools = options.tools;
+    if (options.maxTokens) params.max_tokens = options.maxTokens;
+
+    const response = await this._withRetry(
+      () => this._client.chat.completions.create(params),
+      'Chat (OpenAI)'
+    );
+    this._trackTokens(response.usage);
+
+    const choice = response.choices[0];
+    const toolCalls = (choice.message.tool_calls || []).map(tc => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: JSON.parse(tc.function.arguments),
+    }));
+
+    return {
+      content: choice.message.content || '',
+      toolCalls,
+      stopReason: choice.finish_reason, // 'stop' | 'tool_calls'
+    };
+  }
 }

package/cli/llm-provider.js

@@ -433,6 +433,18 @@ export class LLMProvider {
     throw new Error(`${this.constructor.name} must implement generateJSON()`);
   }
 
+  /**
+   * Multi-turn conversation with tool calling — the agentic loop primitive.
+   * Sends messages + tool definitions, returns the model's response including any tool calls.
+   *
+   * @param {Array} messages - Conversation history [{role, content, toolCalls?, toolCallId?}]
+   * @param {object} options - { tools?, maxTokens?, system? }
+   * @returns {Promise<{ content: string, toolCalls: Array<{id, name, arguments}>, stopReason: string }>}
+   */
+  async chat(messages, options = {}) {
+    throw new Error(`${this.constructor.name} must implement chat()`);
+  }
+
   // Subclass hooks — throw if not overridden
   _createClient() { throw new Error(`${this.constructor.name} must implement _createClient()`); }
   async _callProvider(prompt, maxTokens, systemInstructions) { throw new Error(`${this.constructor.name} must implement _callProvider()`); }

package/cli/llm-xiaomi.js

@@ -140,4 +140,55 @@ export class XiaomiProvider extends LLMProvider {
 
     return content;
   }
+
+  /**
+   * Multi-turn conversation with tool calling (OpenAI-compatible API).
+   */
+  async chat(messages, options = {}) {
+    if (!this._client) this._client = this._createClient();
+
+    const openaiMessages = messages.map(msg => {
+      if (msg.role === 'tool') {
+        return { role: 'tool', tool_call_id: msg.toolCallId, content: msg.content };
+      }
+      if (msg.role === 'assistant' && msg.toolCalls?.length > 0) {
+        return {
+          role: 'assistant',
+          content: msg.content || null,
+          tool_calls: msg.toolCalls.map(tc => ({
+            id: tc.id,
+            type: 'function',
+            function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+          })),
+        };
+      }
+      return { role: msg.role, content: msg.content };
+    });
+
+    const params = {
+      model: this.model,
+      messages: openaiMessages,
+    };
+    if (options.tools?.length > 0) params.tools = options.tools;
+    if (options.maxTokens) params.max_tokens = options.maxTokens;
+
+    const response = await this._withRetry(
+      () => this._client.chat.completions.create(params),
+      'Chat (Xiaomi)'
+    );
+    this._trackTokens(response.usage);
+
+    const choice = response.choices[0];
+    const toolCalls = (choice.message.tool_calls || []).map(tc => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: JSON.parse(tc.function.arguments),
+    }));
+
+    return {
+      content: choice.message.content || '',
+      toolCalls,
+      stopReason: choice.finish_reason,
+    };
+  }
 }

package/cli/seed-processor.js

@@ -779,6 +779,37 @@ Return your response as JSON following the exact structure specified in your ins
       this.debug(`[INFO] Updated story doc.md after task extraction (${storyDocContent.length} bytes)`);
     }
 
+    // Compute ready status for tasks/subtasks with no pending dependencies
+    try {
+      const { checkDependenciesReady } = await import('./dependency-checker.js');
+      const lookup = {};
+      for (const task of hierarchy.tasks) {
+        lookup[task.id] = { id: task.id, name: task.name, type: 'task', status: 'planned', dependencies: task.dependencies || [] };
+        for (const sub of task.subtasks || []) {
+          lookup[sub.id] = { id: sub.id, name: sub.name, type: 'subtask', status: 'planned', dependencies: sub.dependencies || [] };
+        }
+      }
+
+      let readyCount = 0;
+      for (const id of Object.keys(lookup)) {
+        const result = checkDependenciesReady(id, lookup);
+        if (result.ready) {
+          const itemDir = path.join(this.projectPath, id);
+          const wjPath = path.join(itemDir, 'work.json');
+          if (fs.existsSync(wjPath)) {
+            const wj = JSON.parse(fs.readFileSync(wjPath, 'utf8'));
+            wj.status = 'ready';
+            fs.writeFileSync(wjPath, JSON.stringify(wj, null, 2), 'utf8');
+            lookup[id].status = 'ready';
+            readyCount++;
+          }
+        }
+      }
+      this.debug(`[INFO] Set ${readyCount} task/subtask items to 'ready' status (dependency-free)`);
+    } catch (err) {
+      this.debug(`[WARN] Ready status computation failed (non-critical): ${err.message}`);
+    }
+
     return { taskCount, subtaskCount, taskIds };
   }