diff --git a/.agents/reference/task-taxonomy.md b/.agents/reference/task-taxonomy.md new file mode 100644 index 000000000..52459499d --- /dev/null +++ b/.agents/reference/task-taxonomy.md @@ -0,0 +1,66 @@ +--- +description: Canonical routing taxonomy — domain labels and model tier labels for task creation and dispatch +--- + +# Task Taxonomy: Domain and Model Tier Classification + +Single source of truth for the two classification tables used at task creation time +(`/new-task`, `/save-todo`, `/define`) and consumed at dispatch time (`/pulse`). + +When a domain or tier is added or changed, update **only this file**. Command files +reference it by pointer. + +--- + +## Domain Routing Table + +Maps task content to a specialist agent. Used by task creation commands to apply +GitHub labels and TODO tags, and by the pulse to select the `--agent` flag at +dispatch time. + +| Domain Signal | TODO Tag | GitHub Label | Agent | +|--------------|----------|--------------|-------| +| SEO audit, keywords, GSC, schema markup, rankings | `#seo` | `seo` | SEO | +| Blog posts, articles, newsletters, video scripts, social copy | `#content` | `content` | Content | +| Email campaigns, FluentCRM, landing pages | `#marketing` | `marketing` | Marketing | +| Invoicing, receipts, financial ops, bookkeeping | `#accounts` | `accounts` | Accounts | +| Compliance, terms of service, privacy policy, GDPR | `#legal` | `legal` | Legal | +| Tech research, competitive analysis, market research, spikes | `#research` | `research` | Research | +| CRM pipeline, proposals, outreach | `#sales` | `sales` | Sales | +| Social media scheduling, posting, engagement | `#social-media` | `social-media` | Social-Media | +| Video generation, editing, animation, prompts | `#video` | `video` | Video | +| Health and wellness content, nutrition | `#health` | `health` | Health | +| Code: features, bug fixes, refactors, CI, tests | *(none)* | *(none)* | Build+ (default) | + +**Rule:** Omit the domain tag for code tasks — Build+ is the default and needs no +label. Only add a domain tag when the task clearly maps to a specialist domain. + +--- + +## Model Tier Table + +Maps task reasoning complexity to a model tier. Used by task creation commands to +apply `tier:` GitHub labels and TODO tags, and by the pulse to resolve the +`--model` flag at dispatch time via `model-availability-helper.sh resolve `. + +| Tier | TODO Tag | GitHub Label | When to Apply | +|------|----------|--------------|---------------| +| thinking | `tier:thinking` | `tier:thinking` | Architecture decisions, novel design with no existing patterns, complex multi-system trade-offs, security audits requiring deep reasoning | +| simple | `tier:simple` | `tier:simple` | Docs-only changes, simple renames, formatting, config tweaks, label/tag updates | +| *(coding)* | *(none)* | *(none)* | Standard implementation, bug fixes, refactors, tests — **default, no label needed** | + +**Rule:** Default to no tier label — most tasks are coding tasks that use sonnet. +Only add a tier label when the task clearly needs more reasoning power (`thinking`) +or clearly needs less (`simple`). When uncertain, omit. + +--- + +## Usage by Command Files + +- **`/new-task`** — classify after brief creation (Step 6.5); apply labels via `gh issue edit` +- **`/save-todo`** — classify during dispatch tag evaluation (Step 1b) +- **`/define`** — classify during task type detection (Step 1) +- **`/pulse`** — consume labels at dispatch time (Agent routing + Model tier selection sections) + +See `scripts/commands/pulse.md` "Agent routing from labels" and "Model tier selection" +for how these labels are consumed at dispatch time. diff --git a/.agents/scripts/commands/define.md b/.agents/scripts/commands/define.md index c289cca29..a4c4d9be9 100644 --- a/.agents/scripts/commands/define.md +++ b/.agents/scripts/commands/define.md @@ -38,33 +38,10 @@ Parse `$ARGUMENTS` to classify the task. Use keyword signals: | **docs** | document, readme, guide, explain, describe | Accurate, concise, follows existing doc patterns | | **research** | investigate, explore, evaluate, compare, spike | Time-boxed, deliverable is a written recommendation | -Also classify the **agent domain** — this determines which specialist agent handles the task at dispatch time: - -| Domain | Signal Words | Agent | -|--------|-------------|-------| -| **seo** | SEO, keywords, rankings, GSC, schema markup | SEO | -| **content** | blog, article, newsletter, video script, copy | Content | -| **marketing** | campaign, email blast, landing page, FluentCRM | Marketing | -| **accounts** | invoice, receipt, financial, bookkeeping | Accounts | -| **legal** | compliance, terms, privacy policy, GDPR | Legal | -| **research** | market research, competitive analysis, tech spike | Research | -| **sales** | CRM, proposal, outreach, pipeline | Sales | -| **social-media** | social post, scheduling, engagement | Social-Media | -| **video** | video generation, editing, animation | Video | -| **health** | wellness, health content, nutrition | Health | -| *(code)* | implement, fix, refactor, CI, test | Build+ (default — no label needed) | - -Include the domain tag (e.g., `#seo`, `#content`) in the TODO.md entry and as a GitHub label on the issue. Omit for code tasks. - -Also classify the **model tier** — this determines the intelligence level of the worker dispatched for this task: - -| Tier | Tag | Signals | -|------|-----|---------| -| **thinking** | `tier:thinking` | Architecture decisions, novel design with no existing patterns, complex multi-system trade-offs, security audits requiring deep reasoning | -| **simple** | `tier:simple` | Docs-only changes, simple renames/formatting, config tweaks, label/tag updates | -| *(coding)* | *(none)* | Standard implementation, bug fixes, refactors, tests — **default, no tag needed** | - -Default to no tier tag — most tasks are coding (sonnet). Only tag when the task clearly needs more reasoning power or clearly needs less. +Also classify the **agent domain** and **model tier** using the canonical tables in +`reference/task-taxonomy.md`. Include the domain tag (e.g., `#seo`, `#content`) in +the TODO.md entry and as a GitHub label on the issue. Omit both for code tasks +(Build+ is the default; coding tier is the default). If ambiguous, ask: diff --git a/.agents/scripts/commands/new-task.md b/.agents/scripts/commands/new-task.md index 136a0c897..0f0add6d4 100644 --- a/.agents/scripts/commands/new-task.md +++ b/.agents/scripts/commands/new-task.md @@ -185,33 +185,12 @@ If the brief is too thin for auto-dispatch, omit the tag and note why. ### Step 6.5: Apply Model Tier and Agent Routing Labels -**Model tier label** — Evaluate the task's reasoning complexity and add a tier tag. This tells the pulse which model intelligence level to use at dispatch time: - -| Tier | TODO Tag | GitHub Label | When to Apply | -|------|----------|--------------|---------------| -| thinking | `tier:thinking` | `tier:thinking` | Architecture decisions, novel design, complex trade-offs, security audits, multi-system reasoning | -| simple | `tier:simple` | `tier:simple` | Docs-only, simple renames, formatting, config changes, label/tag updates | -| *(coding)* | *(none)* | *(none)* | Standard implementation, bug fixes, refactors, tests — **default, no label needed** | - -**Default to no tier label** — most tasks are coding tasks that use sonnet. Only add a tier label when the task clearly needs more reasoning power (thinking) or clearly needs less (simple). When uncertain, omit the label — sonnet handles the vast majority of work well. - -**Agent routing label** — Evaluate whether the task maps to a specialist agent domain. If it does, add the corresponding tag to the TODO.md entry AND apply the matching GitHub label to the issue (if `task_ref` exists). - -| Domain Signal | TODO Tag | GitHub Label | Agent | -|--------------|----------|--------------|-------| -| SEO audit, keywords, GSC, schema markup, rankings | `#seo` | `seo` | SEO | -| Blog posts, video scripts, newsletters, social copy | `#content` | `content` | Content | -| Email campaigns, FluentCRM, landing pages | `#marketing` | `marketing` | Marketing | -| Invoicing, receipts, financial ops | `#accounts` | `accounts` | Accounts | -| Compliance, terms of service, privacy policy | `#legal` | `legal` | Legal | -| Tech research, competitive analysis, market research | `#research` | `research` | Research | -| CRM pipeline, proposals, outreach | `#sales` | `sales` | Sales | -| Social media scheduling, posting | `#social-media` | `social-media` | Social-Media | -| Video generation, editing, prompts | `#video` | `video` | Video | -| Health and wellness content | `#health` | `health` | Health | -| Code: features, bug fixes, refactors, CI | *(none)* | *(none)* | Build+ (default) | - -**Omit the domain tag for code tasks** — Build+ is the default and needs no label. +Classify the task using the canonical taxonomy tables in +`reference/task-taxonomy.md` — domain routing table and model tier table. + +Add the matching TODO tag to the TODO.md entry AND apply the matching GitHub label +to the issue (if `task_ref` exists). Omit both for standard code tasks (Build+ is +the default; coding tier is the default). If the task clearly matches a domain, apply the label: diff --git a/.agents/scripts/commands/pulse.md b/.agents/scripts/commands/pulse.md index 4d4d65676..e0cc7d9be 100644 --- a/.agents/scripts/commands/pulse.md +++ b/.agents/scripts/commands/pulse.md @@ -276,6 +276,9 @@ Do NOT treat `auto-dispatch` or `status:available` as hard gates. Build candidat ### Agent routing from labels +Labels are applied at task creation time — see `reference/task-taxonomy.md` for the +canonical domain and tier definitions. This section maps those labels to dispatch flags. + Before dispatching, check issue labels for agent routing. This avoids guessing from the title: | Label | Dispatch Flag | Agent | diff --git a/.agents/scripts/commands/save-todo.md b/.agents/scripts/commands/save-todo.md index e2289ac83..9fe0dccfa 100644 --- a/.agents/scripts/commands/save-todo.md +++ b/.agents/scripts/commands/save-todo.md @@ -47,32 +47,9 @@ Every task MUST be evaluated for these pipeline tags: **`#plan`** — Add when the task needs decomposition into subtasks before implementation (multi-phase, >2h, research/design needed). -**Model tier tags** — Evaluate the task's reasoning complexity: - -| Tier | Tag | When to Apply | -|------|-----|---------------| -| thinking | `tier:thinking` | Architecture, novel design, complex trade-offs, security audits | -| simple | `tier:simple` | Docs-only, simple renames, formatting, config changes | -| *(coding)* | *(none)* | Standard implementation, bug fixes, refactors — **default, no tag needed** | - -Default to no tier tag. Most tasks are coding tasks (sonnet). Only tag exceptions. - -**Agent domain tags** — If the task maps to a specialist agent domain, add the corresponding tag. This enables the pulse to route dispatch to the correct agent without guessing from the title: - -| Domain | Tag | Agent | -|--------|-----|-------| -| SEO, keywords, rankings, GSC | `#seo` | SEO | -| Blog posts, newsletters, video scripts | `#content` | Content | -| Email campaigns, landing pages | `#marketing` | Marketing | -| Invoicing, financial ops | `#accounts` | Accounts | -| Compliance, legal docs | `#legal` | Legal | -| Research, analysis, spikes | `#research` | Research | -| CRM, proposals, outreach | `#sales` | Sales | -| Social media management | `#social-media` | Social-Media | -| Video generation/editing | `#video` | Video | -| Health/wellness content | `#health` | Health | - -Omit domain tags for code tasks — Build+ is the default. +**Model tier tags** and **agent domain tags** — classify using the canonical tables +in `reference/task-taxonomy.md`. Omit both for standard code tasks (Build+ is the +default; coding tier is the default). **Default to `#auto-dispatch`** — only omit when a specific exclusion applies. This keeps the autonomous pipeline moving. See `workflows/plans.md` "Auto-Dispatch Tagging" for full criteria.