From 3140dddee4e0253cd22e0cf1ec3e818f86a57fa9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 13 Nov 2025 16:24:44 +0000
Subject: [PATCH 1/3] Initial plan


From 35c960a7d97ea97463b8fa8cbc8a7d4fc77c92b6 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 13 Nov 2025 16:34:24 +0000
Subject: [PATCH 2/3] Document new features: -t flag and task frontmatter
 selectors

- Add -t flag to README and CLI reference
- Document selectors field in task frontmatter
- Update file formats reference with selectors documentation
- Add examples showing task frontmatter selectors and -t flag
- Update how-to guide for creating tasks with embedded selectors

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
---
 README.md                                     | 93 +++++++++++++++++++
 docs/how-to/create-tasks.md                   | 70 ++++++++++++++
 docs/reference/cli.md                         | 42 +++++++++
 docs/reference/file-formats.md                | 68 ++++++++++++++
 examples/agents/tasks/implement-go-feature.md | 55 +++++++++++
 examples/agents/tasks/refactor-code.md        | 57 ++++++++++++
 examples/agents/tasks/write-tests.md          | 52 +++++++++++
 7 files changed, 437 insertions(+)
 create mode 100644 examples/agents/tasks/implement-go-feature.md
 create mode 100644 examples/agents/tasks/refactor-code.md
 create mode 100644 examples/agents/tasks/write-tests.md

diff --git a/README.md b/README.md
index 56f4c18..c882bbb 100644
--- a/README.md
+++ b/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
+...
+```
diff --git a/docs/how-to/create-tasks.md b/docs/how-to/create-tasks.md
index 636caae..7898b30 100644
--- a/docs/how-to/create-tasks.md
+++ b/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
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index eab92e4..1c6dc3e 100644
--- a/docs/reference/cli.md
+++ b/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
diff --git a/docs/reference/file-formats.md b/docs/reference/file-formats.md
index ccf8dd3..f3ee495 100644
--- a/docs/reference/file-formats.md
+++ b/docs/reference/file-formats.md
@@ -63,6 +63,74 @@ region: us-east-1
 coding-context-cli -s environment=production -s region=us-east-1 deploy
 ```
 
+#### `selectors` (optional)
+
+**Type:** Map of key-value pairs  
+**Purpose:** Automatically filter rules and tasks without requiring `-s` flags on the command line
+
+The `selectors` field allows a task to specify which rules should be included when the task is executed. This is equivalent to passing `-s` flags but is declared in the task file itself.
+
+**Example:**
+```yaml
+---
+task_name: implement-feature
+selectors:
+  language: Go
+  stage: implementation
+---
+```
+
+**Usage:**
+```bash
+# Automatically includes 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
+```
+
+**OR Logic with Arrays:**
+
+You can specify multiple values for the same key using YAML arrays for OR logic:
+
+```yaml
+---
+task_name: test-code
+selectors:
+  language: [Go, Python, JavaScript]
+  stage: testing
+---
+```
+
+This matches rules where `(language=Go OR language=Python OR language=JavaScript) AND stage=testing`.
+
+**Combining with Command-Line Selectors:**
+
+Selectors from the task frontmatter and command-line `-s` flags are combined (additive):
+
+```bash
+# Task frontmatter has: selectors.language = Go
+# Command line adds: -s priority=high
+# Result: Rules must match language=Go AND priority=high
+coding-context-cli -s priority=high implement-feature
+```
+
+**Special Selector: `rule_name`**
+
+You can filter to specific rule files by their base filename (without extension):
+
+```yaml
+---
+task_name: my-task
+selectors:
+  rule_name: [security-standards, go-best-practices]
+---
+```
+
+This would only include the rules from `security-standards.md` and `go-best-practices.md`.
+
 ### Parameter Substitution
 
 Use `${parameter_name}` syntax for dynamic values.
diff --git a/examples/agents/tasks/implement-go-feature.md b/examples/agents/tasks/implement-go-feature.md
new file mode 100644
index 0000000..e8ae840
--- /dev/null
+++ b/examples/agents/tasks/implement-go-feature.md
@@ -0,0 +1,55 @@
+---
+task_name: implement-feature
+selectors:
+  language: go
+  stage: implementation
+---
+
+# Implement Feature in Go
+
+You are an expert Go developer implementing a new feature.
+
+## Feature Information
+
+- **Name**: ${feature_name}
+- **Description**: ${feature_description}
+
+## Your Task
+
+1. **Design the Implementation**
+   - Follow Go idioms and best practices
+   - Use existing patterns in the codebase
+   - Keep functions small and focused
+   - Use interfaces for flexibility
+
+2. **Write the Code**
+   - Implement the feature with clean, readable Go code
+   - Add proper error handling
+   - Include necessary comments
+   - Follow the project's code style
+
+3. **Add Tests**
+   - Write table-driven tests (project standard)
+   - Test happy paths and error cases
+   - Aim for >80% code coverage
+   - Use meaningful test names
+
+4. **Update Documentation**
+   - Add godoc comments for exported functions
+   - Update README if needed
+   - Document any new behavior
+
+## Guidelines
+
+This task automatically includes:
+- Go-specific coding rules (via language=Go selector)
+- Implementation-stage guidelines (via stage=implementation selector)
+
+Follow all included rules and best practices.
+
+## Output
+
+Provide:
+- The implementation code
+- Comprehensive tests
+- Documentation updates
diff --git a/examples/agents/tasks/refactor-code.md b/examples/agents/tasks/refactor-code.md
new file mode 100644
index 0000000..34712f4
--- /dev/null
+++ b/examples/agents/tasks/refactor-code.md
@@ -0,0 +1,57 @@
+---
+task_name: refactor-code
+selectors:
+  language: [go, python, javascript]
+  stage: refactoring
+---
+
+# Refactor Code
+
+You are an expert developer tasked with refactoring code to improve quality, maintainability, and performance.
+
+## Refactoring Target
+
+- **Component**: ${component_name}
+- **Files**: ${files_to_refactor}
+- **Goal**: ${refactoring_goal}
+
+## Your Task
+
+1. **Analyze Current Code**
+   - Identify code smells
+   - Find duplicated code
+   - Locate overly complex functions
+   - Review naming and structure
+
+2. **Plan the Refactoring**
+   - Define clear refactoring goals
+   - Identify potential risks
+   - Plan incremental changes
+   - Consider backwards compatibility
+
+3. **Implement Changes**
+   - Make small, focused changes
+   - Extract functions/methods for clarity
+   - Improve naming and readability
+   - Reduce complexity
+   - Remove duplication
+
+4. **Ensure Tests Pass**
+   - Run existing tests after each change
+   - Add tests if coverage is lacking
+   - Verify no behavior changes
+   - Use tests to guide refactoring
+
+## Guidelines
+
+This task automatically includes refactoring-stage rules for Go, Python, OR JavaScript (via array selector).
+
+The selector `language: [go, python, javascript]` means rules matching ANY of these languages will be included, along with rules for stage=refactoring.
+
+## Output
+
+Provide:
+- Analysis of current code issues
+- Refactored code
+- Explanation of improvements made
+- Test results showing no regressions
diff --git a/examples/agents/tasks/write-tests.md b/examples/agents/tasks/write-tests.md
new file mode 100644
index 0000000..35cef91
--- /dev/null
+++ b/examples/agents/tasks/write-tests.md
@@ -0,0 +1,52 @@
+---
+task_name: write-tests
+selectors:
+  stage: testing
+---
+
+# Write Comprehensive Tests
+
+You are an expert developer tasked with writing comprehensive tests.
+
+## Test Requirements
+
+- **Component**: ${component_name}
+- **File(s)**: ${files_to_test}
+
+## Your Task
+
+1. **Analyze the Code**
+   - Understand the functionality being tested
+   - Identify all code paths
+   - Find edge cases and boundary conditions
+   - Review existing tests for patterns
+
+2. **Write Test Cases**
+   - Cover all happy paths
+   - Test error conditions
+   - Test edge cases and boundary values
+   - Test concurrent operations if applicable
+
+3. **Follow Language Conventions**
+   - Use meaningful test names that describe what's being tested
+   - Keep tests isolated and independent
+   - Follow the testing patterns in the codebase
+
+4. **Verify Coverage**
+   - Run tests to ensure they pass
+   - Check code coverage metrics
+   - Aim for >80% coverage
+   - Ensure all critical paths are tested
+
+## Guidelines
+
+This task automatically includes testing-stage guidelines (via stage=testing selector).
+
+Use `-s language=go` or similar if you need language-specific rules.
+
+## Output
+
+Provide:
+- Well-structured test code
+- Test coverage report
+- Any testing utilities or fixtures needed

From b1dfcd0590b013f1c17d71fbe172c3e33f4bc013 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 13 Nov 2025 16:39:35 +0000
Subject: [PATCH 3/3] Update how-to guide and examples README for new features

- Add task frontmatter selectors section to use-selectors guide
- Document -t flag for viewing embedded selectors
- Update examples README with new task files
- Add examples showing array selectors and OR logic

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
---
 docs/how-to/use-selectors.md | 100 +++++++++++++++++++++++++++++++++++
 examples/README.md           |  43 +++++++++++++++
 2 files changed, 143 insertions(+)

diff --git a/docs/how-to/use-selectors.md b/docs/how-to/use-selectors.md
index 14e7230..8e9a838 100644
--- a/docs/how-to/use-selectors.md
+++ b/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:**
diff --git a/examples/README.md b/examples/README.md
index b114c75..0eb3d65 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -93,6 +93,9 @@ Tasks define specific workflows for agents to execute:
 - **`plan-feature.md`**: Creates comprehensive feature plans
 - **`code-review.md`**: Performs code reviews on PRs
 - **`fix-bug.md`**: Analyzes and fixes bugs
+- **`implement-go-feature.md`**: Implements features in Go (with embedded selectors)
+- **`write-tests.md`**: Writes comprehensive tests
+- **`refactor-code.md`**: Refactors code for multiple languages (demonstrates array selectors)
 
 Tasks use parameter substitution for dynamic content:
 
@@ -107,6 +110,40 @@ Issue: #${issue_number}
 Title: ${issue_title}
 ```
 
+**New: Tasks can embed selectors in frontmatter** to automatically filter rules:
+
+```markdown
+---
+task_name: implement-feature
+selectors:
+  language: go
+  stage: implementation
+---
+
+# Implement Feature in Go
+...
+```
+
+When you run this task, it automatically applies the selectors without requiring `-s` flags:
+
+```bash
+# Automatically includes language=go and stage=implementation rules
+coding-context-cli implement-feature
+```
+
+**Array selectors** allow OR logic for the same key:
+
+```markdown
+---
+task_name: refactor-code
+selectors:
+  language: [go, python, javascript]
+  stage: refactoring
+---
+```
+
+This matches rules for ANY of the specified languages.
+
 ## Getting Started
 
 1. **Copy examples to your repository:**
@@ -137,6 +174,12 @@ Title: ${issue_title}
      -s task=code-review \
      -p pr_number=123 \
      code-review
+   
+   # Test tasks with embedded selectors
+   coding-context-cli implement-feature
+   
+   # View task frontmatter with -t flag
+   coding-context-cli -t implement-feature
    ```
 
 4. **Deploy workflows:**