update doc site

Author: synw

docsite/dist/doc/frontend/5.skills.md

@@ -52,15 +52,8 @@ Execute the following instructions:
 
 The `%my-skill` placeholder will be replaced by the content of the skill
 
-## Builtin task skill
+## Task Skills
 
-A `t` skill is available by default, teaching a model how to manage tasks inside `.agents/tasks`. To call it from a prompt:
+Tasks are managed through a dedicated set of skills. Use `%use-tasks` to load the full task reference guide. See the [Tasks documentation](/frontend/tasks) for details on creating and executing tasks.
 
-```
-create a task for [xyz]
-%t
-```
-
-It will create a `[task-name]` directory in `.agents/tasks` with a `state.md` file in it with all the instructions to execute the task later
-
-<a href="javascript:openLink('/frontend/apps')">Next: apps</a>
+<a href="javascript:openLink('/frontend/tasks')">Next: tasks</a>

docsite/dist/doc/frontend/5.skills.md.br

@@ -0,0 +1,307 @@
+# Tasks
+
+Tasks are structured work units that enable agents to plan, track progress, and execute complex multi-step workflows. They provide a persistent checkpoint system — allowing work to be interrupted and resumed later — with clear goals, verifiable success criteria, and progressive state tracking.
+
+While **skills** teach agents *how* to do things (procedures and guidelines), **tasks** define *what* needs to be done (goals, plans, and execution steps).
+
+## Overview
+
+Tasks are stored as markdown files in the `.agents/tasks/[task-name]/` directory. Each task contains structured files that describe goals, a step-by-step plan, and progress tracking.
+
+### Why Use Tasks?
+
+- **Checkpoints** — Interrupt and resume work at any phase
+- **Progress tracking** — Clear visibility into what's done and what remains
+- **Verifiable steps** — Each step has explicit success criteria
+- **Complex workflows** — Break large work into manageable phases
+- **Multi-agent coordination** — Delegate phases to specialized executor agents
+
+## Task Modes
+
+Tasks can be executed in two modes depending on the nature of the work:
+
+### Solo Tasks
+
+A single agent executes all phases sequentially, maintaining unified context throughout.
+
+**Best for:**
+- Reading/analyzing data to produce output
+- Tightly coupled phases with shared state
+- Tasks that fit within one agent's context window
+- Work requiring quick iteration and refinement
+
+```
+[task-name]/
+├── goals.md              # Goals and success criteria
+├── plan.md               # Full execution plan with all phases
+├── state.md              # Progress tracking
+└── notes.md              # Optional: additional context/notes
+```
+
+### Team Tasks
+
+A coordinator agent delegates individual phases to executor agents, each working in isolated context.
+
+**Best for:**
+- Phases requiring different expertise or domains
+- Independent or parallelizable phases
+- Large tasks exceeding one agent's context window
+- Work benefiting from context isolation between phases
+
+```
+[task-name]/
+├── goals.md                      # Goals and success criteria
+├── plan.md                       # Full execution plan (reference)
+├── state.md                      # Progress tracking
+├── coordinator-instructions.md   # Orchestration instructions
+└── phases/
+    ├── phase-1.md                # Individual phase file
+    └── phase-2.md
+```
+
+### Choosing a Mode
+
+Use the `task-mode` skill to evaluate your task against decision criteria. The general rule: if phases need unified context, use solo; if phases benefit from isolation and different expertise, use team.
+
+## Task Files
+
+Each task file serves a specific purpose in the task lifecycle.
+
+### goals.md — Goals and Success Criteria
+
+Defines what the task achieves and how success is measured.
+
+```markdown
+# Goals and Success Criteria: [task-name]
+
+## Primary Goal
+[Clear statement of what the task achieves]
+
+## Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Files Modified
+- `path/to/file` — description of changes
+
+## Exclusions
+[What is NOT included in this task]
+```
+
+### plan.md — Execution Plan
+
+Contains all phases with step-by-step instructions and verifiable success criteria.
+
+```markdown
+# Task Plan: [task-name]
+
+## Phase 1: [Phase Name]
+**Goal:** [What this phase achieves]
+
+### Step 1.1: [Step Name]
+- **File:** `path/to/file`
+- **Action:** [Detailed instructions on what to do]
+- **Verify:** [Verifiable success criteria]
+```
+
+**Rules:** Each step must be atomic (one clear action), specify the file to modify, describe the action, and include verifiable success criteria (e.g., "test passes", "code compiles").
+
+### state.md — Progress Tracking
+
+Tracks current status and what has been completed. Updated after each phase.
+
+```markdown
+# Task State: [task-name]
+
+## Status: [planned | in-progress | completed]
+
+## Phases
+- [ ] Phase 1: [name]
+  - [ ] Step 1.1
+  - [x] Step 1.2 ✓
+- [ ] Phase 2: [name]
+
+## Notes
+- Next: Phase X, Step Y
+```
+
+### notes.md — Optional Context
+
+Additional references, background information, or anything the agent should keep in mind during execution.
+
+### coordinator-instructions.md (Team Only)
+
+Orchestration guide for the coordinator agent — lists phases, step counts, and the delegation workflow.
+
+### phases/phase-X.md (Team Only)
+
+Self-contained phase file with full context and step-by-step instructions. Executor agents read only their assigned phase file.
+
+```markdown
+# Phase X: [Phase Name]
+
+## Context
+- **Task ID:** [task-name]
+- **Current state:** [metrics/status]
+- **Target:** [what we're aiming for]
+
+### Step X.1: [Step Name]
+**File:** `path/to/file`
+**Execution Plan:** [Detailed instructions]
+**Success Criteria:**
+- [ ] Criterion 1 (verifiable)
+```
+
+## Task Skills Ecosystem
+
+The task system is powered by a set of specialized skills. Use `%use-tasks` to load the full reference guide.
+
+### Creation Skills
+
+| Skill | Purpose | When to Use |
+|-------|---------|-------------|
+| `create-task` | Entry point — analyzes request, chooses mode, delegates | User asks to create a new task |
+| `task-mode` | Mode selector — checklist to decide solo vs team | Determining execution mode |
+| `create-task-solo` | Creates task for single-agent execution | Task needs unified context |
+| `create-task-team` | Creates task for multi-agent execution | Task has independent phases |
+
+### Execution Skills
+
+| Skill | Purpose | When to Use |
+|-------|---------|-------------|
+| `execute-task-solo` | Execute a solo task (single agent runs all phases) | Running a solo task |
+| `execute-task-team` | Execute a team task (coordinator delegates to executors) | Coordinator running a team task |
+| `execute-task-phase` | Behavioral contract for executor agents | Executor agent running an assigned phase |
+
+### Reference
+
+| Skill | Purpose |
+|-------|---------|
+| `use-tasks` | Overview of the task system and which skill to use |
+
+## Using Tasks
+
+### Creating a Task
+
+Ask an agent to create a task. The agent will:
+1. Analyze the request
+2. Choose solo or team mode using `task-mode`
+3. Create the task directory structure with all required files
+4. Report the plan to you before execution
+
+```
+Create a task to document the agent-smith-plugins package
+%create-task
+```
+
+### Executing a Task
+
+Use the `load-task` tool to load a task into the workspace, then have an agent execute it:
+
+```
+Execute the maintain-agent-docs task
+%execute-task-solo
+```
+
+The agent will:
+1. Read `state.md` to determine current progress
+2. Execute the next incomplete step from `plan.md`
+3. Verify success criteria
+4. Update `state.md` to mark the step complete
+5. Repeat until all phases are done
+
+### Loading a Task
+
+Use the `load-task` tool to load a task into your workspace:
+
+```
+%use-task maintain-agent-docs
+```
+
+This copies the task files to your workspace for the agent to work with.
+
+## Task Lifecycle
+
+### 1. Create
+The agent creates the task structure (`goals.md`, `plan.md`, `state.md`) and presents it to you for review.
+
+### 2. Execute
+The agent executes phases one by one, updating `state.md` after each completed step. Never skip ahead — always verify success criteria before proceeding.
+
+### 3. Complete
+When all phases are done, the agent asks you to verify the results. Only delete the task directory if you confirm everything is correct.
+
+### 4. Interrupted
+If execution stops mid-way, `state.md` is updated with what was done and what remains. You can resume later by loading the task again.
+
+## Example: Solo Task
+
+Here's how a solo task looks in practice (from the `maintain-agent-docs` task):
+
+**goals.md:**
+```markdown
+# Goals and Success Criteria: maintain-agent-docs
+
+## Primary Goal
+Audit and maintain the AI agent navigation documentation for a single package.
+
+## Success Criteria
+- [ ] Summary accurately describes module purpose
+- [ ] Dependencies list is current
+- [ ] Key Files table includes all important files
+```
+
+**plan.md (excerpt):**
+```markdown
+# Task Plan: maintain-agent-docs
+
+## Step 1: Resolve Package Path
+- Map the package parameter to its directory path
+- **Success Criteria:**
+  - [ ] Package path identified
+  - [ ] Target file path determined
+
+## Step 2: Explore the Module
+- Walk the module's directory tree
+- Identify entry points, key files, dependencies
+- **Success Criteria:**
+  - [ ] All source files identified
+  - [ ] Entry point located
+```
+
+**state.md (excerpt):**
+```markdown
+# Task State: maintain-agent-docs
+
+## Status: completed
+
+## Progress
+
+### Step 1: Resolve Package Path
+- [x] ✓ Package path identified
+- [x] ✓ Target file path determined
+
+### Step 2: Explore the Module
+- [x] ✓ All source files identified
+- [x] ✓ Entry point located
+```
+
+## Best Practices
+
+1. **Keep tasks focused** — One task should have one clear goal. Split complex work into multiple tasks.
+2. **Write verifiable success criteria** — Each step must have criteria that can be objectively checked (e.g., "test passes", "file contains X").
+3. **Update state after each step** — Never batch updates. Always mark progress incrementally.
+4. **Don't skip phases** — Execute steps sequentially; never jump ahead.
+5. **Confirm before deleting** — Always ask the user before removing a completed task directory.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Task not found | Check `.agents/tasks/` directory exists and task name is correct |
+| State not updating | Ensure `state.md` exists in the task directory |
+| Agent skipping steps | Load `execute-task-solo` or `execute-task-team` skill for proper execution rules |
+| Wrong mode chosen | Use `task-mode` skill to re-evaluate before creating the task |
+
+<a href="javascript:openLink('/frontend/skills')">Previous: skills</a>
+<a href="javascript:openLink('/frontend/apps')">Next: apps</a>

docsite/dist/doc/frontend/6.tasks.md

@@ -19,4 +19,6 @@ cd agent-smith-ui
 node scripts/installapp.js debate
 ```
 
-This will install the app and configure the frontend to use it.
+This will install the app and configure the frontend to use it.
+
+<a href="javascript:openLink('/frontend/tasks')">Previous: tasks</a>