updated agent docs

Author: tpae

README.md

@@ -280,10 +280,10 @@ Execute complex, multi-step tasks autonomously with built-in issue tracking and
 
 - **Issue Tracking** — Tasks broken into issues with status, priority, and dependencies
 - **Parallel Tasks** — Run multiple agent tasks simultaneously for increased productivity
-- **Execution Planning** — AI generates step-by-step plans (max 10 steps per issue)
+- **Reasoning Loop** — AI autonomously observes, thinks, acts, and checks in iterative cycles
 - **Working Directory** — Select a folder for file operations with project detection
 - **File Operations** — Read, write, edit, search files with undo support
-- **Discovery** — Automatically detects errors, TODOs, and prerequisites
+- **Follow-up Issues** — Agent creates child issues when it discovers additional work
 - **Clarification** — Agent pauses to ask when tasks are ambiguous
 - **Background Execution** — Tasks continue running after closing the window
 

docs/AGENTS.md

@@ -40,8 +40,8 @@ The working directory determines where file operations can occur. All file paths
 3. The agent will:
    - Analyze your request
    - Create an initial issue
-   - Generate an execution plan
-   - Begin executing steps
+   - Enter the reasoning loop, iteratively calling tools and evaluating progress
+   - Complete the task with a summary artifact
 
 ---
 
@@ -71,13 +71,14 @@ You can run **multiple tasks in parallel**, allowing you to work on different pr
 | **Description** | Detailed explanation and context                |
 | **Result**      | Outcome after completion                        |
 
-### Execution Plans
+### Reasoning Loop
 
-When working on an issue, the agent generates an **execution plan** — a step-by-step sequence of actions:
+When working on an issue, the agent enters a **reasoning loop** -- an iterative cycle where the model autonomously decides what to do next:
 
-- Plans are bounded to **max 10 tool calls** per issue
-- Each step uses available tools (file operations, shell commands, etc.)
-- If a task is too large, it's automatically **decomposed** into subtasks
+- Each iteration: the model observes context, reasons about the next action, calls a tool, and evaluates progress
+- Loops are bounded to **max 30 iterations** per issue
+- The model narrates its thinking and explains actions as it works
+- When finished, the model calls `complete_task` to signal completion with a summary
 
 ### Dependencies
 
@@ -86,18 +87,18 @@ Issues can have **dependencies** that control execution order:
 | Relationship      | Description                                      |
 | ----------------- | ------------------------------------------------ |
 | `blocks`          | One issue must complete before another can start |
-| `parent_child`    | Issue was decomposed from a larger issue         |
+| `parent_child`    | Child issue created from a parent task            |
 | `discovered_from` | Issue was discovered during execution of another |
 
-### Discovery
+### Follow-up Issues
 
-During execution, the agent may **discover** additional work:
+During execution, the agent may discover additional work and create **follow-up issues** using the `create_issue` tool:
 
-- **Errors** — Compilation errors, runtime failures
-- **TODOs** — Code comments indicating pending work
+- **Bugs** — Compilation errors, runtime failures found during execution
+- **Related work** — Additional tasks identified while working on the current issue
 - **Prerequisites** — Missing dependencies or setup steps
 
-Discovered items become new issues automatically tracked in the issue list.
+Follow-up issues are automatically tracked in the issue list and linked to the originating issue.
 
 ---
 
@@ -159,6 +160,15 @@ Agents have access to specialized tools for file and system operations:
 | `git_diff`   | Display file differences                       |
 | `git_commit` | Stage and commit changes (requires permission) |
 
+### Agent Control
+
+| Tool                    | Description                                                |
+| ----------------------- | ---------------------------------------------------------- |
+| `complete_task`         | Mark the current task as complete with a summary artifact  |
+| `create_issue`          | Create a follow-up issue for discovered work               |
+| `request_clarification` | Pause execution to ask the user a question                 |
+| `generate_artifact`     | Generate a standalone document (report, analysis, etc.)    |
+
 All tools:
 
 - Validate paths are within the working directory
@@ -254,8 +264,8 @@ This reduces token usage while maintaining access to all capabilities.
      │                │                   │
      │                │                   │
      ▼                ▼                   ▼
-  Created         Executing          Waiting on
-  by user        plan steps         dependencies
+  Created       Reasoning loop       Waiting on
+  by user        iterating          dependencies
   or agent
 ```
 

docs/FEATURES.md

@@ -392,23 +392,23 @@ Canonical reference for all Osaurus features, their status, and documentation.
 - `Agent/AgentFolderTools.swift` — File and shell operation tools
 - `Agent/AgentFileOperation.swift` — File operation models
 - `Agent/AgentFileOperationLog.swift` — Operation logging with undo support
-- `Models/AgentModels.swift` — Core data models (Issue, AgentTask, ExecutionPlan, etc.)
+- `Models/AgentModels.swift` — Core data models (Issue, AgentTask, LoopState, etc.)
 - `Services/AgentEngine.swift` — Main task execution coordinator
-- `Services/AgentExecutionEngine.swift` — Plan generation and step execution
+- `Services/AgentExecutionEngine.swift` — Reasoning loop execution engine
 - `Managers/IssueManager.swift` — Issue lifecycle and dependency management
-- `Storage/AgentDatabase.swift` — SQLite storage for issues, tasks, and events
-- `Tools/AgentTools.swift` — Agent-specific tools (submit_plan, report_discovery, complete_task)
+- `Storage/AgentDatabase.swift` — SQLite storage for issues, tasks, and conversation turns
+- `Tools/AgentTools.swift` — Agent-specific tools (complete_task, create_issue, generate_artifact, etc.)
 - `Views/AgentView.swift` — Main Agent Mode UI
 - `Views/AgentSession.swift` — Observable session state manager
 
 **Features:**
 
 - **Issue Tracking** — Tasks broken into issues with status, priority, type, and dependencies
 - **Parallel Tasks** — Run multiple agent tasks simultaneously for increased productivity
-- **Execution Planning** — AI generates step-by-step plans (max 10 tool calls per issue)
+- **Reasoning Loop** — AI autonomously iterates through observe-think-act-check cycles (max 30 iterations)
 - **Working Directory** — Select a folder for file operations with project type detection
 - **File Operations** — Read, write, edit, search, move, copy, delete files with undo support
-- **Discovery** — Automatic detection of errors, TODOs, and prerequisites during execution
+- **Follow-up Issues** — Agent creates child issues via `create_issue` tool when it discovers additional work
 - **Clarification** — Agent pauses to ask when tasks are ambiguous
 - **Background Execution** — Tasks continue running after closing the window
 - **Token Usage Tracking** — Monitor cumulative input/output tokens per task
@@ -443,15 +443,15 @@ Canonical reference for all Osaurus features, their status, and documentation.
 | `git_diff`      | Display file differences                       |
 | `git_commit`    | Stage and commit changes (requires permission) |
 
-**Workflow:**
+**Workflow (Reasoning Loop):**
 
 1. User input creates a task with an initial issue
-2. Agent generates an execution plan (max 10 steps)
-3. Steps are executed sequentially, calling tools as needed
-4. Discovery detects errors, TODOs, or prerequisites during execution
-5. Verification checks if goal achieved after steps complete
-6. Large tasks are automatically decomposed into subtasks
-7. Clarification pauses execution when task is ambiguous
+2. Agent enters a reasoning loop (max 30 iterations per issue)
+3. Each iteration: the model observes context, decides on an action, calls a tool, and evaluates progress
+4. The model narrates its reasoning and explains actions as it works
+5. When additional work is found, the agent creates follow-up issues via `create_issue`
+6. When the task is complete, the agent calls `complete_task` with a summary and artifact
+7. Clarification pauses execution when the task is ambiguous
 
 **Storage:** `~/.osaurus/agent/agent.db` (SQLite)