Docs: linearWebhook source type undocumented in reference and missing from examples index

[kelos-bot]

🤖 Kelos User Agent @gjkim42

Problem

The linearWebhook source type is fully implemented (types, filters with action/states/labels/excludeLabels) but is completely absent from docs/reference.md. A new user trying to set up a Linear-driven TaskSpawner has no reference for the available fields.

Additionally, example 11-taskspawner-linear-webhook/ exists in the repository but is not listed in examples/README.md — the table ends at example 10.

Evidence

• grep -r "linear" docs/ → no matches
• api/v1alpha1/taskspawner_types.go:386-425 defines LinearWebhook and LinearWebhookFilter with full field set:
  • spec.when.linearWebhook.types — required list of Linear resource types (e.g., "Issue")
  • spec.when.linearWebhook.filters[].type — scope filter to a specific resource type
  • spec.when.linearWebhook.filters[].action — create, update, or remove
  • spec.when.linearWebhook.filters[].states — workflow state names (e.g., "Todo", "In Progress")
  • spec.when.linearWebhook.filters[].labels — require all of these labels
  • spec.when.linearWebhook.filters[].excludeLabels — exclude issues with any of these labels
• examples/README.md table lists examples 01–10 but omits 11-taskspawner-linear-webhook/

Suggested Fix

1. Add a spec.when.linearWebhook section to docs/reference.md (TaskSpawner table), documenting each field alongside the existing githubWebhook entries.
2. Add example 11 to the examples/README.md table:

   | [11-taskspawner-linear-webhook](11-taskspawner-linear-webhook/) | Respond to Linear webhook events (issues, comments) in real time |
   

3. Consider adding a promptTemplate variables column for linearWebhook to the variables table in docs/reference.md.

[kelos-bot]

🤖 Kelos Task Status

Task kelos-triage-905 has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kelos Triage Report

Kind: kind/docs
Priority: priority/important-longterm — Docs gap for a fully implemented feature; users can work around it by reading the API types or the example directly, but it hurts discoverability
Actor: actor/kelos — Concrete, well-scoped docs additions with objectively verifiable acceptance criteria

Status: STILL VALID

Evidence:

• docs/reference.md contains zero mentions of "linear" — confirmed via grep
• examples/README.md table lists examples 01–10 only; example 11 (11-taskspawner-linear-webhook/) exists in the repo with README.md and taskspawner.yaml but is not indexed
• api/v1alpha1/taskspawner_types.go defines LinearWebhook struct (line 386) and LinearWebhookFilter (line 403) with full field set (types, filters[].type, filters[].action, filters[].states, filters[].labels, filters[].excludeLabels)
• No merged PRs or recent commits reference this issue or address this docs gap

Duplicates found: None found

Recommendation: KEEP OPEN — The three changes described in the issue (add linearWebhook section to reference.md, add example 11 to examples/README.md table, add promptTemplate variables for linearWebhook) are clear and actionable.