@taskforcehq/taskforce 0.3.170 → 0.3.301

package/src/resources/templates/workflow-sources/workflowDocs.mjs

@@ -1,6 +1,6 @@
 const MIN_VERSION = '0.3.13-beta.2';
-const ALLOWED_STATUSES = ['task', 'on-hold', 'in-progress', 'review'];
-const FORBIDDEN_STATUSES = ['done', 'cancelled'];
+const ALLOWED_STATUSES = ['task', 'on-hold', 'in-progress', 'review', 'done'];
+const FORBIDDEN_STATUSES = ['cancelled'];
 
 const baseToolPolicy = (criticalTools, forbiddenTools = []) => ({
     requiredToolsPolicy: {
@@ -19,6 +19,8 @@ const baseContextPolicy = {
     sourcePriority: ['mcp'],
     mcp: {
         knownTaskIdTool: '{{MCP_PREFIX}}get_task',
+        taskAttachmentListTool: '{{MCP_PREFIX}}get_task_attachments',
+        taskAttachmentReadTool: '{{MCP_PREFIX}}read_task_attachment',
         unknownTaskIdTools: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks']
     },
     mcpUnavailableAction: 'stop-and-request-user-action'
@@ -29,6 +31,8 @@ const protocolBlock = (label) => [
     '> 1. **MCP-first load**:',
     '>    - If task ID is known, call `{{MCP_PREFIX}}get_task`.',
     '>    - If task ID is unknown, use `{{MCP_PREFIX}}list_tasks` / `{{MCP_PREFIX}}search_tasks` to identify it.',
+    '>    - If task attachments may matter, call `{{MCP_PREFIX}}get_task_attachments` and then `{{MCP_PREFIX}}read_task_attachment` for the specific files you need.',
+    '>    - Do not try to open task attachment HTTP paths directly when MCP attachment-read tools are available.',
     '>    - If MCP is unavailable, stop and request user action.',
     '> 2. Print `prompts.startupChecklist`.'
 ].join('\n');
@@ -53,7 +57,7 @@ export const workflowDocs = [
         compat: {
             minTaskforceVersion: MIN_VERSION,
             requiredToolsCritical: ['{{MCP_PREFIX}}get_task'],
-            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}attach_context_file', '{{MCP_PREFIX}}save_task_attachment']
+            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}get_task_attachments', '{{MCP_PREFIX}}read_task_attachment', '{{MCP_PREFIX}}link_task_context', '{{MCP_PREFIX}}save_task_attachment']
         },
         toolPolicy: baseToolPolicy(['{{MCP_PREFIX}}get_task']),
         contextPolicy: baseContextPolicy,
@@ -100,11 +104,11 @@ export const workflowDocs = [
         },
         compat: {
             minTaskforceVersion: MIN_VERSION,
-            requiredToolsCritical: ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}add_comment'],
-            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}get_config', '{{MCP_PREFIX}}create_task', '{{MCP_PREFIX}}attach_context_file', '{{MCP_PREFIX}}save_task_attachment']
+            requiredToolsCritical: ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}add_comment', '{{MCP_PREFIX}}finish_task'],
+            requiredToolsOptional: ['{{MCP_PREFIX}}resolve_profile', '{{MCP_PREFIX}}list_assignees', '{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}get_task_attachments', '{{MCP_PREFIX}}read_task_attachment', '{{MCP_PREFIX}}get_config', '{{MCP_PREFIX}}create_task', '{{MCP_PREFIX}}link_task_context', '{{MCP_PREFIX}}save_task_attachment']
         },
         toolPolicy: baseToolPolicy(
-            ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}add_comment'],
+            ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}add_comment', '{{MCP_PREFIX}}finish_task'],
             ['{{MCP_PREFIX}}archive_task']
         ),
         artifacts: {
@@ -121,12 +125,13 @@ export const workflowDocs = [
                 "3.  [ ] **Specialists Loaded**: [List names or 'None']"
             ].join('\n'),
             handoffChecklist: [
-                '- [ ] Status set to `review` unless user explicitly requested another allowed status',
+                '- [ ] Final status set with `{{MCP_PREFIX}}finish_task`',
+                '- [ ] Used `done` when no explicit human validation was requested, or `review` when human validation/approval was needed',
                 '- [ ] Summary comment added with `{{MCP_PREFIX}}add_comment`',
                 '- [ ] `walkthrough.md` updated',
-                '- [ ] Parent/child links changed only when explicitly requested',
+                '- [ ] Planning relationships changed only when explicitly requested',
                 '- [ ] Did NOT call `{{MCP_PREFIX}}archive_task`',
-                '- [ ] Did NOT set `done` or `cancelled` unless explicitly instructed'
+                '- [ ] Did NOT set `cancelled` unless explicitly instructed'
             ].join('\n')
         },
         content: {
@@ -154,36 +159,38 @@ export const workflowDocs = [
                 '   - If task complexity is `3` to `5`, create or refresh `implementation_plan.md` before major code edits.',
                 '   - If complexity is below `3`, planning is optional.',
                 '2. **Task management mode gate (required before task mutations)**:',
-                '   - Choose exactly one mode and state it explicitly: `checklist_mode` or `decompose_mode`.',
+                '   - Choose exactly one mode and state it explicitly: `checklist_mode` or `planning_mode`.',
                 '   - Default to `checklist_mode` for linear/short execution.',
-                '   - Use `decompose_mode` only when at least one is true:',
+                '   - Use `planning_mode` only when at least one is true:',
                 '     - multi-system or multi-owner work',
                 '     - meaningful parallelization',
                 '     - expected duration > 1 day',
                 '     - explicit dependency/risk tracking is needed',
-                '     - user explicitly asks for subtasks',
-                '3. **Owner strategy gate (required before task creation/update)**:',
-                '   - Set ownership explicitly with `owner` (alias of `assignee`): `user`, `agent`, or `unassigned`.',
-                '   - If user console/credential action is required, set `owner=user`.',
-                '   - If AI can execute independently, set `owner=agent`.',
-                '   - If unclear, set `owner=unassigned` and add a clarification note.',
+                '     - user explicitly asks for more structural planning context',
+                '3. **Identity + owner strategy gate (required before task creation/update)**:',
+                '   - Call `{{MCP_PREFIX}}resolve_profile` before creating tasks, assigning tasks, or adding agent-authored comments.',
+                '   - Stateless client pattern: call `{{MCP_PREFIX}}resolve_profile`, save the returned `profileToken`, and include `profileToken` on later mutating calls if the client does not preserve session state.',
+                '   - Use the returned profile ID directly when assigning work to yourself.',
+                '   - Call `{{MCP_PREFIX}}list_assignees` before assigning tasks to someone else, then use a concrete workspace member ID or AI profile ID.',
+                '   - Never use generic owner values like `agent` or `user`.',
+                '   - If unclear who should own the work, set `owner=unassigned` and add a clarification note.',
                 '4. **Preflight confirmation gate (required before creating multiple tasks)**:',
-                '   - Confirm mode: `checklist_mode` vs `decompose_mode`.',
-                '   - Confirm owner default: `user` / `agent` / `mixed`.',
+                '   - Confirm mode: `checklist_mode` vs `planning_mode`.',
+                '   - Confirm owner default: a concrete assignee ID, `unassigned`, or a mixed plan with explicit IDs.',
                 '   - Confirm whether assignment should be set immediately.',
                 '5. **Config gate**:',
                 '   - Before setting category/type/priority/approach/status/complexity, call `{{MCP_PREFIX}}get_config`.',
+                '   - Treat `{{MCP_PREFIX}}get_config` as the source of truth for taxonomy and enum values; do not rely on remembered type/category names.',
                 '6. **Set active state**:',
                 '   - Set status to `in-progress` with `{{MCP_PREFIX}}update_task`.',
                 '',
                 '### Phase B: Execution',
                 '1. Implement code changes.',
                 '2. Run validation steps (automated tests + manual checks as needed).',
-                '3. If user requests relationship work:',
-                '   - Link/unlink/re-parent using `{{MCP_PREFIX}}update_task` (`parentTaskId`).',
-                '   - Create child tasks using `{{MCP_PREFIX}}create_task` with `parentTaskId` set.',
-                '   - Every created child task must include explicit `owner`/`assignee`.',
-                '   - Re-parent only after explicit user confirmation.',
+                '3. If user requests planning relationship work:',
+                '   - Link/unlink a task to a workstream using `{{MCP_PREFIX}}set_task_workstream` or `{{MCP_PREFIX}}clear_task_workstream`.',
+                '   - Link/unlink a workstream to an initiative using `{{MCP_PREFIX}}set_workstream_initiative` or `{{MCP_PREFIX}}clear_workstream_initiative`.',
+                '   - Create new tasks/workstreams/initiatives only when they materially improve execution clarity.',
                 '4. If blocked, switch to Collaborate mode and capture blocker context.',
                 '',
                 '### Phase C: Handover',
@@ -192,10 +199,12 @@ export const workflowDocs = [
                 '   - Validation evidence',
                 '   - Remaining risks',
                 '2. Add summary comment with `{{MCP_PREFIX}}add_comment`.',
-                '3. Set status to `review` via `{{MCP_PREFIX}}update_task` unless user explicitly requests another allowed status (`task`, `on-hold`, `in-progress`, `review`).',
-                '   - If setting status to `task` or `on-hold`, add explicit comment justification using `{{MCP_PREFIX}}add_comment`.',
-                '4. Never set `done` or `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
-                '5. Do not auto-set parent tasks to `done` or `cancelled` due to child changes; only do so if user explicitly instructs.',
+                '3. Use `{{MCP_PREFIX}}finish_task` for final handoff.',
+                '   - Use `outcome: "done"` when the work is complete and no explicit human validation is requested.',
+                '   - Use `outcome: "review"` when human validation or approval is still needed.',
+                '   - When uncertain, prefer `review`.',
+                '4. Never set `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
+                '5. Do not change sibling or related task statuses unless the user explicitly instructs it.',
                 '6. Print `prompts.handoffChecklist` and stop.'
             ].join('\n')
         }
@@ -211,7 +220,7 @@ export const workflowDocs = [
         compat: {
             minTaskforceVersion: MIN_VERSION,
             requiredToolsCritical: ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}add_comment'],
-            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}get_config', '{{MCP_PREFIX}}attach_context_file', '{{MCP_PREFIX}}save_task_attachment']
+            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}get_task_attachments', '{{MCP_PREFIX}}read_task_attachment', '{{MCP_PREFIX}}get_config', '{{MCP_PREFIX}}link_task_context', '{{MCP_PREFIX}}save_task_attachment']
         },
         toolPolicy: baseToolPolicy(
             ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}add_comment'],
@@ -219,7 +228,7 @@ export const workflowDocs = [
         ),
         artifacts: {
             implementationPlan: {
-                path: '.taskforce/task-data/{taskId}/attachments/implementation-plan.md',
+                path: 'task attachment "implementation-plan.md"',
                 required: false,
                 savePolicy: 'ask-before-save'
             }
@@ -245,6 +254,7 @@ export const workflowDocs = [
                 '## 1. Startup (Mandatory)',
                 '',
                 '1. Call `{{MCP_PREFIX}}get_config` before setting category/type/priority/approach/status/complexity.',
+                '   - Treat `{{MCP_PREFIX}}get_config` as the source of truth for taxonomy and enum values; do not rely on remembered type/category names.',
                 '2. Set status to `in-progress` via `{{MCP_PREFIX}}update_task`.',
                 '3. Load specialist instructions for the active environment and acknowledge constraints.',
                 '4. Load all relevant context sources tied to the task.',
@@ -254,9 +264,9 @@ export const workflowDocs = [
                 '## 2. Planning Deliverable',
                 '',
                 '0. Choose and record task management mode for follow-on execution:',
-                '   - `checklist_mode` (single parent + in-task checklist) for linear short work.',
-                '   - `decompose_mode` (child tasks) only when dependencies/parallelism/risk tracking justify decomposition.',
-                '   - Record owner strategy: `user`, `agent`, or `mixed`.',
+                '   - `checklist_mode` (single task + in-task checklist) for linear short work.',
+                '   - `planning_mode` (tasks grouped into workstreams/initiatives) only when structure improves clarity, dependencies, or ownership.',
+                '   - Record owner strategy as explicit assignee IDs, `unassigned`, or a mixed plan with explicit IDs.',
                 '',
                 '1. Define file-level change plan (exact files and intended changes).',
                 '2. Identify compatibility and regression risks.',
@@ -274,9 +284,9 @@ export const workflowDocs = [
                 '   - `### Next Action`',
                 '6. Ask whether to save as `{artifacts.implementationPlan.path}`.',
                 '7. If user confirms, persist task-specific content via `{{MCP_PREFIX}}save_task_attachment` using `filename: "implementation-plan.md"`.',
-                '   - Use `{{MCP_PREFIX}}attach_context_file` only for linking existing files/URLs (for example, shared docs under `docs/`).',
+                '   - Use `{{MCP_PREFIX}}link_task_context` only for linking existing files/URLs (for example, shared docs under `docs/`).',
                 '8. If setting status to `task` or `on-hold`, add explicit comment justification using `{{MCP_PREFIX}}add_comment`.',
-                '9. Never set `done` or `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
+                '9. Never set `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
                 '10. Print `prompts.handoffPrompt` and stop.'
             ].join('\n')
         }
@@ -292,7 +302,7 @@ export const workflowDocs = [
         compat: {
             minTaskforceVersion: MIN_VERSION,
             requiredToolsCritical: ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}add_comment'],
-            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}attach_context_file', '{{MCP_PREFIX}}save_task_attachment']
+            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}get_task_attachments', '{{MCP_PREFIX}}read_task_attachment', '{{MCP_PREFIX}}link_task_context', '{{MCP_PREFIX}}save_task_attachment']
         },
         toolPolicy: baseToolPolicy(
             ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}add_comment'],
@@ -300,7 +310,7 @@ export const workflowDocs = [
         ),
         artifacts: {
             collaborationBlueprint: {
-                path: '.taskforce/task-data/{taskId}/attachments/collaboration-blueprint.md',
+                path: 'task attachment "collaboration-blueprint.md"',
                 required: false,
                 savePolicy: 'ask-before-save'
             }
@@ -348,10 +358,10 @@ export const workflowDocs = [
                 '   - `### Next Step`',
                 '4. Ask whether to save as `{artifacts.collaborationBlueprint.path}`.',
                 '5. If user confirms, persist task-specific content via `{{MCP_PREFIX}}save_task_attachment` using `filename: "collaboration-blueprint.md"`.',
-                '   - Use `{{MCP_PREFIX}}attach_context_file` only for linking existing files/URLs (for example, shared docs under `docs/`).',
+                '   - Use `{{MCP_PREFIX}}link_task_context` only for linking existing files/URLs (for example, shared docs under `docs/`).',
                 '6. Ask concise clarification questions only if required fields above are missing.',
                 '7. If setting status to `task` or `on-hold`, add explicit comment justification using `{{MCP_PREFIX}}add_comment`.',
-                '8. Never set `done` or `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
+                '8. Never set `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
                 '9. Ask user whether to proceed to `/plan`.',
                 '10. Stop.'
             ].join('\n')
@@ -368,7 +378,7 @@ export const workflowDocs = [
         compat: {
             minTaskforceVersion: MIN_VERSION,
             requiredToolsCritical: ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}add_comment'],
-            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}get_config', '{{MCP_PREFIX}}attach_context_file', '{{MCP_PREFIX}}save_task_attachment']
+            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}get_task_attachments', '{{MCP_PREFIX}}read_task_attachment', '{{MCP_PREFIX}}get_config', '{{MCP_PREFIX}}link_task_context', '{{MCP_PREFIX}}save_task_attachment']
         },
         toolPolicy: baseToolPolicy(
             ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}add_comment'],
@@ -376,7 +386,7 @@ export const workflowDocs = [
         ),
         artifacts: {
             evaluationReport: {
-                path: '.taskforce/task-data/{taskId}/attachments/evaluation.md',
+                path: 'task attachment "evaluation.md"',
                 required: false,
                 savePolicy: 'ask-before-save'
             }
@@ -425,14 +435,14 @@ export const workflowDocs = [
                 '   - `### Next Step`',
                 '4. Ask whether to save as `{artifacts.evaluationReport.path}`.',
                 '5. If user confirms, persist task-specific content via `{{MCP_PREFIX}}save_task_attachment` using `filename: "evaluation.md"`.',
-                '   - Use `{{MCP_PREFIX}}attach_context_file` only for linking existing files/URLs (for example, shared docs under `docs/`).',
-                '6. Never set `done` or `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
+                '   - Use `{{MCP_PREFIX}}link_task_context` only for linking existing files/URLs (for example, shared docs under `docs/`).',
+                '6. Never set `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
                 '',
                 '## 3. Optional Report Artifact',
                 '',
                 '1. Use report files only when user opts in.',
-                '2. Save to `.taskforce/task-data/{taskId}/attachments/evaluation.md` and attach to task context when approved.',
-                '   - If the document is not task-specific, store it under `docs/` and optionally link it with `{{MCP_PREFIX}}attach_context_file`.',
+                '2. Save to `task attachment "evaluation.md"` and attach to task context when approved.',
+                '   - If the document is not task-specific, store it under `docs/` and optionally link it with `{{MCP_PREFIX}}link_task_context`.',
                 '3. Stop.'
             ].join('\n')
         }
@@ -448,7 +458,7 @@ export const workflowDocs = [
         compat: {
             minTaskforceVersion: MIN_VERSION,
             requiredToolsCritical: ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}add_comment'],
-            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}attach_context_file', '{{MCP_PREFIX}}save_task_attachment']
+            requiredToolsOptional: ['{{MCP_PREFIX}}list_tasks', '{{MCP_PREFIX}}search_tasks', '{{MCP_PREFIX}}get_task_attachments', '{{MCP_PREFIX}}read_task_attachment', '{{MCP_PREFIX}}update_task', '{{MCP_PREFIX}}link_task_context', '{{MCP_PREFIX}}save_task_attachment']
         },
         toolPolicy: baseToolPolicy(
             ['{{MCP_PREFIX}}get_task', '{{MCP_PREFIX}}add_comment'],
@@ -456,7 +466,7 @@ export const workflowDocs = [
         ),
         artifacts: {
             reviewReport: {
-                path: '.taskforce/task-data/{taskId}/attachments/review.md',
+                path: 'task attachment "review.md"',
                 required: false,
                 savePolicy: 'ask-before-save'
             }
@@ -503,16 +513,16 @@ export const workflowDocs = [
                 '   - `### Next Status`',
                 '3. Ask whether to save as `{artifacts.reviewReport.path}`.',
                 '4. If user confirms, persist task-specific content via `{{MCP_PREFIX}}save_task_attachment` using `filename: "review.md"`.',
-                '   - Use `{{MCP_PREFIX}}attach_context_file` only for linking existing files/URLs (for example, shared docs under `docs/`).',
-                '5. Keep status within allowed statuses (`task`, `on-hold`, `in-progress`, `review`) unless user explicitly instructs otherwise.',
+                '   - Use `{{MCP_PREFIX}}link_task_context` only for linking existing files/URLs (for example, shared docs under `docs/`).',
+                '5. Keep status within allowed statuses (`task`, `on-hold`, `in-progress`, `review`, `done`) unless user explicitly instructs otherwise.',
                 '   - If setting status to `task` or `on-hold`, add explicit comment justification using `{{MCP_PREFIX}}add_comment`.',
-                '6. Never set `done` or `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
+                '6. Never set `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.',
                 '',
                 '## 3. Optional Report Artifact',
                 '',
                 '1. Use report files only when user opts in.',
-                '2. Save to `.taskforce/task-data/{taskId}/attachments/review.md` and attach to task context when approved.',
-                '   - If the document is not task-specific, store it under `docs/` and optionally link it with `{{MCP_PREFIX}}attach_context_file`.',
+                '2. Save to `task attachment "review.md"` and attach to task context when approved.',
+                '   - If the document is not task-specific, store it under `docs/` and optionally link it with `{{MCP_PREFIX}}link_task_context`.',
                 '3. Stop.'
             ].join('\n')
         }

package/src/resources/templates/workflows/collaborate.yaml

@@ -17,7 +17,9 @@ compat:
   requiredToolsOptional:
     - "{{MCP_PREFIX}}list_tasks"
     - "{{MCP_PREFIX}}search_tasks"
-    - "{{MCP_PREFIX}}attach_context_file"
+    - "{{MCP_PREFIX}}get_task_attachments"
+    - "{{MCP_PREFIX}}read_task_attachment"
+    - "{{MCP_PREFIX}}link_task_context"
     - "{{MCP_PREFIX}}save_task_attachment"
 toolPolicy:
   requiredToolsPolicy:
@@ -34,12 +36,12 @@ toolPolicy:
       - on-hold
       - in-progress
       - review
-    forbiddenStatuses:
       - done
+    forbiddenStatuses:
       - cancelled
 artifacts:
   collaborationBlueprint:
-    path: .taskforce/task-data/{taskId}/attachments/collaboration-blueprint.md
+    path: task attachment "collaboration-blueprint.md"
     required: false
     savePolicy: ask-before-save
 contextPolicy:
@@ -47,6 +49,8 @@ contextPolicy:
     - mcp
   mcp:
     knownTaskIdTool: "{{MCP_PREFIX}}get_task"
+    taskAttachmentListTool: "{{MCP_PREFIX}}get_task_attachments"
+    taskAttachmentReadTool: "{{MCP_PREFIX}}read_task_attachment"
     unknownTaskIdTools:
       - "{{MCP_PREFIX}}list_tasks"
       - "{{MCP_PREFIX}}search_tasks"
@@ -65,6 +69,8 @@ content:
     > 1. **MCP-first load**:
     >    - If task ID is known, call `{{MCP_PREFIX}}get_task`.
     >    - If task ID is unknown, use `{{MCP_PREFIX}}list_tasks` / `{{MCP_PREFIX}}search_tasks` to identify it.
+    >    - If task attachments may matter, call `{{MCP_PREFIX}}get_task_attachments` and then `{{MCP_PREFIX}}read_task_attachment` for the specific files you need.
+    >    - Do not try to open task attachment HTTP paths directly when MCP attachment-read tools are available.
     >    - If MCP is unavailable, stop and request user action.
     > 2. Print `prompts.startupChecklist`.
 
@@ -96,9 +102,9 @@ content:
        - `### Next Step`
     4. Ask whether to save as `{artifacts.collaborationBlueprint.path}`.
     5. If user confirms, persist task-specific content via `{{MCP_PREFIX}}save_task_attachment` using `filename: "collaboration-blueprint.md"`.
-       - Use `{{MCP_PREFIX}}attach_context_file` only for linking existing files/URLs (for example, shared docs under `docs/`).
+       - Use `{{MCP_PREFIX}}link_task_context` only for linking existing files/URLs (for example, shared docs under `docs/`).
     6. Ask concise clarification questions only if required fields above are missing.
     7. If setting status to `task` or `on-hold`, add explicit comment justification using `{{MCP_PREFIX}}add_comment`.
-    8. Never set `done` or `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.
+    8. Never set `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.
     9. Ask user whether to proceed to `/plan`.
     10. Stop.

package/src/resources/templates/workflows/do.yaml

@@ -23,7 +23,9 @@ compat:
   requiredToolsOptional:
     - "{{MCP_PREFIX}}list_tasks"
     - "{{MCP_PREFIX}}search_tasks"
-    - "{{MCP_PREFIX}}attach_context_file"
+    - "{{MCP_PREFIX}}get_task_attachments"
+    - "{{MCP_PREFIX}}read_task_attachment"
+    - "{{MCP_PREFIX}}link_task_context"
     - "{{MCP_PREFIX}}save_task_attachment"
 toolPolicy:
   requiredToolsPolicy:
@@ -37,14 +39,16 @@ toolPolicy:
       - on-hold
       - in-progress
       - review
-    forbiddenStatuses:
       - done
+    forbiddenStatuses:
       - cancelled
 contextPolicy:
   sourcePriority:
     - mcp
   mcp:
     knownTaskIdTool: "{{MCP_PREFIX}}get_task"
+    taskAttachmentListTool: "{{MCP_PREFIX}}get_task_attachments"
+    taskAttachmentReadTool: "{{MCP_PREFIX}}read_task_attachment"
     unknownTaskIdTools:
       - "{{MCP_PREFIX}}list_tasks"
       - "{{MCP_PREFIX}}search_tasks"
@@ -64,6 +68,8 @@ content:
     > 1. **MCP-first load**:
     >    - If task ID is known, call `{{MCP_PREFIX}}get_task`.
     >    - If task ID is unknown, use `{{MCP_PREFIX}}list_tasks` / `{{MCP_PREFIX}}search_tasks` to identify it.
+    >    - If task attachments may matter, call `{{MCP_PREFIX}}get_task_attachments` and then `{{MCP_PREFIX}}read_task_attachment` for the specific files you need.
+    >    - Do not try to open task attachment HTTP paths directly when MCP attachment-read tools are available.
     >    - If MCP is unavailable, stop and request user action.
     > 2. Print `prompts.startupChecklist`.
 

package/src/resources/templates/workflows/evaluate.yaml

@@ -18,8 +18,10 @@ compat:
   requiredToolsOptional:
     - "{{MCP_PREFIX}}list_tasks"
     - "{{MCP_PREFIX}}search_tasks"
+    - "{{MCP_PREFIX}}get_task_attachments"
+    - "{{MCP_PREFIX}}read_task_attachment"
     - "{{MCP_PREFIX}}get_config"
-    - "{{MCP_PREFIX}}attach_context_file"
+    - "{{MCP_PREFIX}}link_task_context"
     - "{{MCP_PREFIX}}save_task_attachment"
 toolPolicy:
   requiredToolsPolicy:
@@ -37,12 +39,12 @@ toolPolicy:
       - on-hold
       - in-progress
       - review
-    forbiddenStatuses:
       - done
+    forbiddenStatuses:
       - cancelled
 artifacts:
   evaluationReport:
-    path: .taskforce/task-data/{taskId}/attachments/evaluation.md
+    path: task attachment "evaluation.md"
     required: false
     savePolicy: ask-before-save
 contextPolicy:
@@ -50,6 +52,8 @@ contextPolicy:
     - mcp
   mcp:
     knownTaskIdTool: "{{MCP_PREFIX}}get_task"
+    taskAttachmentListTool: "{{MCP_PREFIX}}get_task_attachments"
+    taskAttachmentReadTool: "{{MCP_PREFIX}}read_task_attachment"
     unknownTaskIdTools:
       - "{{MCP_PREFIX}}list_tasks"
       - "{{MCP_PREFIX}}search_tasks"
@@ -68,6 +72,8 @@ content:
     > 1. **MCP-first load**:
     >    - If task ID is known, call `{{MCP_PREFIX}}get_task`.
     >    - If task ID is unknown, use `{{MCP_PREFIX}}list_tasks` / `{{MCP_PREFIX}}search_tasks` to identify it.
+    >    - If task attachments may matter, call `{{MCP_PREFIX}}get_task_attachments` and then `{{MCP_PREFIX}}read_task_attachment` for the specific files you need.
+    >    - Do not try to open task attachment HTTP paths directly when MCP attachment-read tools are available.
     >    - If MCP is unavailable, stop and request user action.
     > 2. Print `prompts.startupChecklist`.
 
@@ -100,12 +106,12 @@ content:
        - `### Next Step`
     4. Ask whether to save as `{artifacts.evaluationReport.path}`.
     5. If user confirms, persist task-specific content via `{{MCP_PREFIX}}save_task_attachment` using `filename: "evaluation.md"`.
-       - Use `{{MCP_PREFIX}}attach_context_file` only for linking existing files/URLs (for example, shared docs under `docs/`).
-    6. Never set `done` or `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.
+       - Use `{{MCP_PREFIX}}link_task_context` only for linking existing files/URLs (for example, shared docs under `docs/`).
+    6. Never set `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.
 
     ## 3. Optional Report Artifact
 
     1. Use report files only when user opts in.
-    2. Save to `.taskforce/task-data/{taskId}/attachments/evaluation.md` and attach to task context when approved.
-       - If the document is not task-specific, store it under `docs/` and optionally link it with `{{MCP_PREFIX}}attach_context_file`.
+    2. Save to `task attachment "evaluation.md"` and attach to task context when approved.
+       - If the document is not task-specific, store it under `docs/` and optionally link it with `{{MCP_PREFIX}}link_task_context`.
     3. Stop.

package/src/resources/templates/workflows/execute.yaml

@@ -16,12 +16,17 @@ compat:
     - "{{MCP_PREFIX}}get_task"
     - "{{MCP_PREFIX}}update_task"
     - "{{MCP_PREFIX}}add_comment"
+    - "{{MCP_PREFIX}}finish_task"
   requiredToolsOptional:
+    - "{{MCP_PREFIX}}resolve_profile"
+    - "{{MCP_PREFIX}}list_assignees"
     - "{{MCP_PREFIX}}list_tasks"
     - "{{MCP_PREFIX}}search_tasks"
+    - "{{MCP_PREFIX}}get_task_attachments"
+    - "{{MCP_PREFIX}}read_task_attachment"
     - "{{MCP_PREFIX}}get_config"
     - "{{MCP_PREFIX}}create_task"
-    - "{{MCP_PREFIX}}attach_context_file"
+    - "{{MCP_PREFIX}}link_task_context"
     - "{{MCP_PREFIX}}save_task_attachment"
 toolPolicy:
   requiredToolsPolicy:
@@ -31,6 +36,7 @@ toolPolicy:
     - "{{MCP_PREFIX}}get_task"
     - "{{MCP_PREFIX}}update_task"
     - "{{MCP_PREFIX}}add_comment"
+    - "{{MCP_PREFIX}}finish_task"
   forbiddenTools:
     - "{{MCP_PREFIX}}archive_task"
   statusTransitions:
@@ -39,8 +45,8 @@ toolPolicy:
       - on-hold
       - in-progress
       - review
-    forbiddenStatuses:
       - done
+    forbiddenStatuses:
       - cancelled
 artifacts:
   walkthrough:
@@ -51,6 +57,8 @@ contextPolicy:
     - mcp
   mcp:
     knownTaskIdTool: "{{MCP_PREFIX}}get_task"
+    taskAttachmentListTool: "{{MCP_PREFIX}}get_task_attachments"
+    taskAttachmentReadTool: "{{MCP_PREFIX}}read_task_attachment"
     unknownTaskIdTools:
       - "{{MCP_PREFIX}}list_tasks"
       - "{{MCP_PREFIX}}search_tasks"
@@ -61,12 +69,13 @@ prompts:
     2.  [ ] **Mode**: [execute]
     3.  [ ] **Specialists Loaded**: [List names or 'None']
   handoffChecklist: |-
-    - [ ] Status set to `review` unless user explicitly requested another allowed status
+    - [ ] Final status set with `{{MCP_PREFIX}}finish_task`
+    - [ ] Used `done` when no explicit human validation was requested, or `review` when human validation/approval was needed
     - [ ] Summary comment added with `{{MCP_PREFIX}}add_comment`
     - [ ] `walkthrough.md` updated
     - [ ] Parent/child links changed only when explicitly requested
     - [ ] Did NOT call `{{MCP_PREFIX}}archive_task`
-    - [ ] Did NOT set `done` or `cancelled` unless explicitly instructed
+    - [ ] Did NOT set `cancelled` unless explicitly instructed
 content:
   default: |-
     # Taskforce Execute Workflow (v2)
@@ -75,6 +84,8 @@ content:
     > 1. **MCP-first load**:
     >    - If task ID is known, call `{{MCP_PREFIX}}get_task`.
     >    - If task ID is unknown, use `{{MCP_PREFIX}}list_tasks` / `{{MCP_PREFIX}}search_tasks` to identify it.
+    >    - If task attachments may matter, call `{{MCP_PREFIX}}get_task_attachments` and then `{{MCP_PREFIX}}read_task_attachment` for the specific files you need.
+    >    - Do not try to open task attachment HTTP paths directly when MCP attachment-read tools are available.
     >    - If MCP is unavailable, stop and request user action.
     > 2. Print `prompts.startupChecklist`.
 
@@ -97,25 +108,28 @@ content:
        - If task complexity is `3` to `5`, create or refresh `implementation_plan.md` before major code edits.
        - If complexity is below `3`, planning is optional.
     2. **Task management mode gate (required before task mutations)**:
-       - Choose exactly one mode and state it explicitly: `checklist_mode` or `decompose_mode`.
-       - Default to `checklist_mode` for linear/short execution.
-       - Use `decompose_mode` only when at least one is true:
+       - Choose a management approach and state it explicitly: single-task execution, checklist-driven execution, or planning-entity decomposition.
+       - Default to checklist-driven execution for linear/short work.
+       - Use planning-entity decomposition only when at least one is true:
          - multi-system or multi-owner work
          - meaningful parallelization
          - expected duration > 1 day
          - explicit dependency/risk tracking is needed
-         - user explicitly asks for subtasks
-    3. **Owner strategy gate (required before task creation/update)**:
-       - Set ownership explicitly with `owner` (alias of `assignee`): `user`, `agent`, or `unassigned`.
-       - If user console/credential action is required, set `owner=user`.
-       - If AI can execute independently, set `owner=agent`.
-       - If unclear, set `owner=unassigned` and add a clarification note.
+         - user explicitly asks for multiple tracked units of work
+    3. **Identity + owner strategy gate (required before task creation/update)**:
+       - Call `{{MCP_PREFIX}}resolve_profile` before creating tasks, assigning tasks, or adding agent-authored comments.
+       - Stateless client pattern: call `{{MCP_PREFIX}}resolve_profile`, save the returned `profileToken`, and include `profileToken` on later mutating calls if the client does not preserve session state.
+       - Use the returned profile ID directly when assigning work to yourself.
+       - Call `{{MCP_PREFIX}}list_assignees` before assigning tasks to someone else, then use a concrete workspace member ID or AI profile ID.
+       - Never use generic owner values like `agent` or `user`.
+       - If unclear who should own the work, set `owner=unassigned` and add a clarification note.
     4. **Preflight confirmation gate (required before creating multiple tasks)**:
-       - Confirm mode: `checklist_mode` vs `decompose_mode`.
-       - Confirm owner default: `user` / `agent` / `mixed`.
+       - Confirm management approach: single task, checklist, or planning decomposition.
+       - Confirm owner default: a concrete assignee ID, `unassigned`, or a mixed plan with explicit IDs.
        - Confirm whether assignment should be set immediately.
     5. **Config gate**:
        - Before setting category/type/priority/approach/status/complexity, call `{{MCP_PREFIX}}get_config`.
+       - Treat `{{MCP_PREFIX}}get_config` as the source of truth for taxonomy and enum values; do not rely on remembered type/category names.
     6. **Set active state**:
        - Set status to `in-progress` with `{{MCP_PREFIX}}update_task`.
 
@@ -123,10 +137,11 @@ content:
     1. Implement code changes.
     2. Run validation steps (automated tests + manual checks as needed).
     3. If user requests relationship work:
-       - Link/unlink/re-parent using `{{MCP_PREFIX}}update_task` (`parentTaskId`).
-       - Create child tasks using `{{MCP_PREFIX}}create_task` with `parentTaskId` set.
-       - Every created child task must include explicit `owner`/`assignee`.
-       - Re-parent only after explicit user confirmation.
+       - Link/unlink tasks to workstreams using `{{MCP_PREFIX}}set_task_workstream` or `{{MCP_PREFIX}}clear_task_workstream`.
+       - Link/unlink workstreams to initiatives using `{{MCP_PREFIX}}set_workstream_initiative` or `{{MCP_PREFIX}}clear_workstream_initiative`.
+       - Use `{{MCP_PREFIX}}replace_task_checklist` when the work should stay inside a single task with structured checklist tracking.
+       - Every newly created task must include explicit `owner`/`assignee` using a concrete assignee ID or `unassigned`.
+       - Change planning relationships only after explicit user confirmation.
     4. If blocked, switch to Collaborate mode and capture blocker context.
 
     ### Phase C: Handover
@@ -135,8 +150,10 @@ content:
        - Validation evidence
        - Remaining risks
     2. Add summary comment with `{{MCP_PREFIX}}add_comment`.
-    3. Set status to `review` via `{{MCP_PREFIX}}update_task` unless user explicitly requests another allowed status (`task`, `on-hold`, `in-progress`, `review`).
-       - If setting status to `task` or `on-hold`, add explicit comment justification using `{{MCP_PREFIX}}add_comment`.
-    4. Never set `done` or `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.
-    5. Do not auto-set parent tasks to `done` or `cancelled` due to child changes; only do so if user explicitly instructs.
+    3. Use `{{MCP_PREFIX}}finish_task` for final handoff.
+       - Use `outcome: "done"` when the work is complete and no explicit human validation is requested.
+       - Use `outcome: "review"` when human validation or approval is still needed.
+       - When uncertain, prefer `review`.
+    4. Never set `cancelled`, and never call `{{MCP_PREFIX}}archive_task`, unless explicitly instructed by the user.
+    5. Do not change sibling or related task statuses unless the user explicitly instructs it.
     6. Print `prompts.handoffChecklist` and stop.