From 06c225e3bd4c80dd1431008cd52b6962e7e27d64 Mon Sep 17 00:00:00 2001 From: kami Date: Wed, 24 Jun 2026 09:40:44 +0000 Subject: [PATCH] feat(tasks): teach agents when to use the task tools The task tools were registered but had only mechanical descriptions and no standing policy, so agents knew the tools existed but not when to reach for them. Lead each of the five descriptions with its trigger (when to use, when not to) and add a task-tracking convention to .correx/project.toml, which is rendered into every stage's L0 context. Co-Authored-By: Claude Opus 4.8 --- .correx/project.toml | 1 + .../correx/infrastructure/tools/task/TaskContextTool.kt | 5 +++-- .../com/correx/infrastructure/tools/task/TaskCreateTool.kt | 5 ++++- .../com/correx/infrastructure/tools/task/TaskDeleteTool.kt | 5 +++-- .../com/correx/infrastructure/tools/task/TaskSearchTool.kt | 6 ++++-- .../com/correx/infrastructure/tools/task/TaskUpdateTool.kt | 7 ++++--- 6 files changed, 19 insertions(+), 10 deletions(-) diff --git a/.correx/project.toml b/.correx/project.toml index 3556a92d..3bf52623 100644 --- a/.correx/project.toml +++ b/.correx/project.toml @@ -5,6 +5,7 @@ conventions = [ "Dependency direction: apps -> core -> infrastructure; no cross-core imports", "No bare try-catch; use runCatching and sealed domain error types", "Every new EventPayload must be registered in the eventModule polymorphic block (Serialization.kt)", + "Track multi-session or handoff work as native tasks: search before creating to avoid duplicates (task_search), task_context before starting, claim before working, submit_for_review when ready, complete after review. Don't open a task for a single self-contained edit you finish now.", ] [commands] diff --git a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskContextTool.kt b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskContextTool.kt index 38953f8d..cdb121a9 100644 --- a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskContextTool.kt +++ b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskContextTool.kt @@ -25,8 +25,9 @@ class TaskContextTool(private val assembler: TaskContextAssembler) : Tool, ToolE override val name: String = "task_context" override val description: String = - "Fetch a task's context bundle (goal, acceptance criteria, resolved dependencies, " + - "related links, relevant files, notes) in one call. Use before working a task." + "Call this first, before working a task you've claimed or been pointed at, so you don't " + + "re-derive context: it returns the task's goal, acceptance criteria, resolved " + + "dependencies, related links, relevant files, and notes in one bundle." override val parametersSchema: JsonObject = buildJsonObject { put("type", "object") putJsonObject("properties") { diff --git a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskCreateTool.kt b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskCreateTool.kt index d1f5b90c..357860d3 100644 --- a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskCreateTool.kt +++ b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskCreateTool.kt @@ -22,7 +22,10 @@ class TaskCreateTool(private val service: TaskService) : Tool, ToolExecutor { override val name: String = "task_create" override val description: String = - "Create a task in a project's work graph and return its id (e.g. 'auth-142')." + "Open a task when work spans multiple sessions, needs handoff between runs, or the " + + "operator asks to track it. Search first (task_search) to avoid duplicates. Don't " + + "create one for a single self-contained edit you finish now. Returns the new id " + + "(e.g. 'auth-142')." override val parametersSchema: JsonObject = buildJsonObject { put("type", "object") putJsonObject("properties") { diff --git a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskDeleteTool.kt b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskDeleteTool.kt index 0442fe8a..b47eded1 100644 --- a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskDeleteTool.kt +++ b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskDeleteTool.kt @@ -26,8 +26,9 @@ class TaskDeleteTool(private val service: TaskService) : Tool, ToolExecutor { override val name: String = "task_delete" override val description: String = - "Soft-delete a task (removes it from active views; history is kept). " + - "For an abandoned-but-visible task, use task_update action=cancel instead." + "Use only to remove a task opened by mistake or a duplicate: soft-deletes it (drops " + + "from active views; history is kept). For real work that's been abandoned, use " + + "task_update action=cancel instead so it stays visible." override val parametersSchema: JsonObject = buildJsonObject { put("type", "object") putJsonObject("properties") { diff --git a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskSearchTool.kt b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskSearchTool.kt index a4b80c39..dc287d4e 100644 --- a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskSearchTool.kt +++ b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskSearchTool.kt @@ -28,8 +28,10 @@ class TaskSearchTool(private val service: TaskService) : Tool, ToolExecutor { override val name: String = "task_search" override val description: String = - "Search tasks by text (matches id/title/goal/acceptance criteria/notes), ranked by " + - "relevance. Returns 'id [STATUS] title' lines. Use to find a task id, then task_context." + "Search tasks before opening a new one (avoid duplicates) and to find related or " + + "blocking work, or to look up a task id by text. Matches id/title/goal/acceptance " + + "criteria/notes, ranked by relevance; returns 'id [STATUS] title' lines. Pair with " + + "task_context to load a hit." override val parametersSchema: JsonObject = buildJsonObject { put("type", "object") putJsonObject("properties") { diff --git a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskUpdateTool.kt b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskUpdateTool.kt index 7b0607b2..bf37d5d7 100644 --- a/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskUpdateTool.kt +++ b/infrastructure/tools/src/main/kotlin/com/correx/infrastructure/tools/task/TaskUpdateTool.kt @@ -29,9 +29,10 @@ class TaskUpdateTool(private val service: TaskService) : Tool, ToolExecutor { override val name: String = "task_update" override val description: String = - "Update a task: edit title/goal/criteria/paths, change status via 'action' " + - "(claim, release, block, unblock, submit_for_review, complete, reopen, cancel), " + - "add a link, or add a note." + "Keep a task's state current as you work it: claim before starting, submit_for_review " + + "when ready, complete after review, block/unblock when waiting on something. Also " + + "edits title/goal/criteria/paths, adds a work-graph link, or attaches a note. " + + "Actions: claim, release, block, unblock, submit_for_review, complete, reopen, cancel." override val parametersSchema: JsonObject = buildJsonObject { put("type", "object") putJsonObject("properties") {