Document task frontmatter selectors and -t flag

README.md

@@ -70,6 +70,7 @@ Options:
   -s value
     	Include rules with matching frontmatter. Can be specified multiple times as key=value.
     	Note: Only matches top-level YAML fields in frontmatter.
+  -t	Print task frontmatter at the beginning of output.
 ```
 
 ### Examples
@@ -253,6 +254,56 @@ coding-context-cli -s environment=staging deploy
 coding-context-cli -s environment=production deploy
 ```
 
+#### Task Frontmatter Selectors
+
+Task files can include a `selectors` field in their frontmatter to automatically filter rules without requiring explicit `-s` flags on the command line. This is useful for tasks that always need specific rules.
+
+**Example (`.agents/tasks/implement-go-feature.md`):**
+```markdown
+---
+task_name: implement-feature
+selectors:
+  language: Go
+  stage: implementation
+---
+# Implement Feature
+
+Implement the feature following Go best practices and implementation guidelines.
+```
+
+When you run this task, it automatically applies the selectors:
+```bash
+# This command automatically includes only rules with language=Go and stage=implementation
+coding-context-cli implement-feature
+```
+
+This is equivalent to:
+```bash
+coding-context-cli -s language=Go -s stage=implementation implement-feature
+```
+
+**Selectors support OR logic for the same key using arrays:**
+```markdown
+---
+task_name: test-code
+selectors:
+  language: [Go, Python]
+  stage: testing
+---
+```
+
+This will include rules that match `(language=Go OR language=Python) AND stage=testing`.
+
+**Combining task selectors with command-line selectors:**
+
+Selectors from both the task frontmatter and command line are combined (additive):
+```bash
+# Task has: selectors.language = Go
+# Command adds: -s priority=high
+# Result: includes rules matching language=Go AND priority=high
+coding-context-cli -s priority=high implement-feature
+```
+
 ### Resume Mode
 
 Resume mode is designed for continuing work on a task where you've already established context. When using the `-r` flag:
@@ -403,3 +454,45 @@ then
     # Add installation commands here
 fi
 ```
+
+### Emitting Task Frontmatter
+
+The `-t` flag allows you to include the task's YAML frontmatter at the beginning of the output. This is useful when the AI agent or downstream tool needs access to metadata about the task being executed.
+
+**Example usage:**
+```bash
+coding-context-cli -t -p issue_number=123 fix-bug
+```
+
+**Output format:**
+```yaml
+---
+task_name: fix-bug
+resume: false
+---
+# Fix Bug Task
+
+Fix the bug in issue #123...
+```
+
+This can be useful for:
+- **Agent decision making**: The AI can see metadata like priority, environment, or stage
+- **Workflow automation**: Downstream tools can parse the frontmatter to make decisions
+- **Debugging**: You can verify which task variant was selected and what selectors were applied
+
+**Example with selectors in frontmatter:**
+```bash
+coding-context-cli -t implement-feature
+```
+
+If the task has `selectors` in its frontmatter, they will be visible in the output:
+```yaml
+---
+task_name: implement-feature
+selectors:
+  language: Go
+  stage: implementation
+---
+# Implementation Task
+...
+```

docs/how-to/create-tasks.md

@@ -130,6 +130,76 @@ coding-context-cli -s resume=false refactor
 coding-context-cli -r refactor
 ```
 
+## Tasks with Embedded Selectors
+
+Instead of requiring `-s` flags on every invocation, you can embed selectors directly in the task frontmatter. This is useful for tasks that always need specific rules.
+
+**Example (`.agents/tasks/implement-go-feature.md`):**
+```markdown
+---
+task_name: implement-feature
+selectors:
+  language: Go
+  stage: implementation
+---
+# Implement Feature in Go
+
+Implement the feature following Go best practices and implementation guidelines.
+
+Feature name: ${feature_name}
+Requirements: ${requirements}
+```
+
+**Usage:**
+```bash
+# Automatically applies language=Go and stage=implementation selectors
+coding-context-cli -p feature_name="User Auth" implement-feature
+```
+
+**Example with OR logic using arrays:**
+```markdown
+---
+task_name: write-tests
+selectors:
+  language: [Go, Python]
+  stage: testing
+---
+# Write Tests
+
+Write comprehensive tests for the code.
+```
+
+This matches rules where `(language=Go OR language=Python) AND stage=testing`.
+
+**Combining embedded and command-line selectors:**
+```bash
+# Task has: selectors.language = Go
+# Command adds: -s priority=high
+# Result: Includes rules matching language=Go AND priority=high
+coding-context-cli -s priority=high implement-feature
+```
+
+## Emitting Task Frontmatter
+
+Use the `-t` flag to include the task frontmatter in the output. This is useful when downstream tools need access to task metadata.
+
+**Example:**
+```bash
+coding-context-cli -t implement-feature
+```
+
+**Output:**
+```yaml
+---
+task_name: implement-feature
+selectors:
+  language: Go
+  stage: implementation
+---
+# Implement Feature in Go
+...
+```
+
 ## Best Practices
 
 1. **Use descriptive task names**: Make them clear and specific

docs/how-to/use-selectors.md

@@ -123,6 +123,106 @@ coding-context-cli -s resume=true fix-bug  # but also skips rules
 
 Use resume mode when continuing work in a new session to save tokens.
 
+## Task Frontmatter Selectors
+
+Instead of specifying selectors on the command line every time, you can embed them directly in task files using the `selectors` field.
+
+### Basic Task Selectors
+
+**Task file (`.agents/tasks/implement-go-feature.md`):**
+```markdown
+---
+task_name: implement-feature
+selectors:
+  language: go
+  stage: implementation
+---
+# Implement Feature in Go
+...
+```
+
+**Usage:**
+```bash
+# Automatically applies language=go and stage=implementation
+coding-context-cli implement-feature
+```
+
+This is equivalent to:
+```bash
+coding-context-cli -s language=go -s stage=implementation implement-feature
+```
+
+### Array Selectors (OR Logic)
+
+Use arrays for OR logic within the same selector key:
+
+**Task file:**
+```markdown
+---
+task_name: refactor-code
+selectors:
+  language: [go, python, javascript]
+  stage: refactoring
+---
+```
+
+**Usage:**
+```bash
+# Includes rules matching (go OR python OR javascript) AND refactoring
+coding-context-cli refactor-code
+```
+
+### Combining Command-Line and Task Selectors
+
+Selectors from task frontmatter and the command line are combined (additive):
+
+**Task file with embedded selectors:**
+```markdown
+---
+task_name: deploy
+selectors:
+  stage: deployment
+---
+```
+
+**Usage:**
+```bash
+# Combines task selectors with command-line selectors
+# Result: stage=deployment AND environment=production
+coding-context-cli -s environment=production deploy
+```
+
+### When to Use Task Frontmatter Selectors
+
+**Use task frontmatter selectors when:**
+- A task always needs specific rules (e.g., language-specific tasks)
+- You want to simplify command-line invocations
+- The selectors are intrinsic to the task's purpose
+
+**Use command-line selectors when:**
+- Selectors vary between invocations
+- You need runtime flexibility
+- Multiple users run the same task differently
+
+### Viewing Task Frontmatter
+
+Use the `-t` flag to see which selectors are embedded in a task:
+
+```bash
+coding-context-cli -t implement-feature
+```
+
+**Output:**
+```yaml
+---
+task_name: implement-feature
+selectors:
+  language: go
+  stage: implementation
+---
+# Task content...
+```
+
 ## Understanding Selector Matching
 
 **Rules are included if:**

docs/reference/cli.md

@@ -147,6 +147,48 @@ coding-context-cli -s language=Go -s priority=high fix-bug
 coding-context-cli -s environment=production deploy
 ```
 
+### `-t`
+
+**Type:** Boolean flag  
+**Default:** False
+
+Print the task's YAML frontmatter at the beginning of the output. This includes all frontmatter fields such as `task_name`, `selectors`, `resume`, and any custom fields.
+
+Use this when downstream tools or AI agents need access to task metadata for decision-making or workflow automation.
+
+**Example:**
+```bash
+# Emit task frontmatter with the assembled context
+coding-context-cli -t fix-bug
+```
+
+**Output:**
+```yaml
+---
+task_name: fix-bug
+resume: false
+---
+# Fix Bug Task
+...
+```
+
+**Example with selectors:**
+```bash
+coding-context-cli -t implement-feature
+```
+
+If the task includes `selectors` in frontmatter, they appear in the output:
+```yaml
+---
+task_name: implement-feature
+selectors:
+  language: Go
+  stage: implementation
+---
+# Implementation
+...
+```
+
 ## Exit Codes
 
 - `0` - Success