Add selector support to command frontmatter (#168)

* Initial plan

* Add support for command frontmatter selectors

- Added Selectors field to CommandFrontMatter struct
- Updated findCommand to extract and merge command selectors with task selectors
- Added table-driven tests for command selectors functionality
- Created example command file with selectors

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Update documentation for command selectors feature

- Added documentation for selectors field in command frontmatter
- Explained how command selectors combine with task selectors
- Provided examples of using command selectors

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

* Refactor selector merging to reduce code duplication

- Extracted mergeSelectors helper function
- Updated task and command selector handling to use the helper
- Addresses code review feedback

Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>

Author: Copilot

docs/reference/file-formats.md

@@ -468,6 +468,46 @@ coding-context -p environment=prod -p version=1.0 my-task
 
 This is useful when commands contain template syntax that should be preserved.
 
+#### `selectors` (optional)
+
+**Type:** Map of key-value pairs  
+**Purpose:** Specifies selectors that filter which rules are included when this command is used. Command selectors are combined with task selectors and CLI selectors using OR logic.
+
+When a task uses a command that has selectors, those selectors are merged with the task's selectors to filter rules. This allows commands to specify which rules they need (e.g., database-specific rules, authentication rules, etc.).
+
+**Example:**
+```yaml
+---
+selectors:
+  database: postgres
+  feature: auth
+---
+
+# Database Setup Instructions
+
+This command provides database setup instructions.
+```
+
+**Usage in a task:**
+```yaml
+---
+selectors:
+  env: production
+---
+
+Deploy to production environment.
+
+/setup-database
+```
+
+When this task runs:
+- Rules with `env: production` will be included (from task selector)
+- Rules with `database: postgres` will be included (from command selector)
+- Rules with `feature: auth` will be included (from command selector)
+- Rules that match any of these selectors will be included (OR logic)
+
+This allows commands to declare their dependencies on specific rules without requiring every task to manually specify them.
+
 ### Slash Command Syntax
 
 Commands are referenced from tasks using slash command syntax:

examples/agents/commands/setup-database.md

@@ -0,0 +1,22 @@
+---
+selectors:
+  database: postgres
+  feature: auth
+---
+
+# Database Setup Instructions
+
+This command provides database setup instructions. When this command is used in a task,
+it will automatically include rules that are tagged with `database: postgres` and 
+`feature: auth` in their frontmatter.
+
+## PostgreSQL Configuration
+
+Connect to PostgreSQL:
+```bash
+psql -U ${db_user} -d ${db_name}
+```
+
+## Authentication Setup
+
+Configure authentication tables and initial data.

pkg/codingcontext/context.go

@@ -126,16 +126,7 @@ func (cc *Context) findTask(taskName string) error {
 		// rules match if their frontmatter value matches ANY selector value for a given key.
 		// For example: if CLI has env=development and task has env=production,
 		// rules with either env=development OR env=production will be included.
-		for key, value := range frontMatter.Selectors {
-			switch v := value.(type) {
-			case []any:
-				for _, item := range v {
-					cc.includes.SetValue(key, fmt.Sprint(item))
-				}
-			default:
-				cc.includes.SetValue(key, fmt.Sprint(v))
-			}
-		}
+		cc.mergeSelectors(frontMatter.Selectors)
 
 		// Task frontmatter agent field overrides -a flag
 		if frontMatter.Agent != "" {
@@ -210,9 +201,11 @@ func (cc *Context) findTask(taskName string) error {
 }
 
 // findCommand searches for a command markdown file and returns its content.
-// Commands now support optional frontmatter with the expand field.
+// Commands now support optional frontmatter with the expand field and selectors.
 // Parameters are substituted by default (when expand is nil or true).
 // Substitution is skipped only when expand is explicitly set to false.
+// If the command has selectors in its frontmatter, they are merged into cc.includes
+// to allow commands to specify which rules they need.
 func (cc *Context) findCommand(commandName string, params taskparser.Params) (string, error) {
 	var content *string
 	err := cc.visitMarkdownFiles(commandSearchPaths, func(path string) error {
@@ -228,6 +221,11 @@ func (cc *Context) findCommand(commandName string, params taskparser.Params) (st
 			return err
 		}
 
+		// Extract selector labels from command frontmatter and add them to cc.includes.
+		// This combines CLI selectors, task selectors, and command selectors using OR logic:
+		// rules match if their frontmatter value matches ANY selector value for a given key.
+		cc.mergeSelectors(frontMatter.Selectors)
+
 		// Expand parameters only if expand is not explicitly set to false
 		var processedContent string
 		if shouldExpandParams(frontMatter.ExpandParams) {
@@ -251,6 +249,22 @@ func (cc *Context) findCommand(commandName string, params taskparser.Params) (st
 	return *content, nil
 }
 
+// mergeSelectors adds selectors from a map into cc.includes.
+// This is used to combine selectors from task and command frontmatter with CLI selectors.
+// The merge uses OR logic: rules match if their frontmatter value matches ANY selector value for a given key.
+func (cc *Context) mergeSelectors(selectors map[string]any) {
+	for key, value := range selectors {
+		switch v := value.(type) {
+		case []any:
+			for _, item := range v {
+				cc.includes.SetValue(key, fmt.Sprint(item))
+			}
+		default:
+			cc.includes.SetValue(key, fmt.Sprint(v))
+		}
+	}
+}
+
 // expandParams performs all types of content expansion:
 // - Parameter expansion: ${param_name}
 // - Command expansion: !`command`

pkg/codingcontext/context_test.go

@@ -867,6 +867,70 @@ func TestContext_Run_Commands(t *testing.T) {
 				}
 			},
 		},
+		{
+			name: "command with selectors filters rules",
+			setup: func(t *testing.T, dir string) {
+				// Task uses a command that has selectors
+				createTask(t, dir, "task-with-cmd", "", "/setup-db")
+				// Command has selectors that should be applied to rule filtering
+				createCommand(t, dir, "setup-db", "selectors:\n  database: postgres", "Setting up database...")
+				// Rules with different database values
+				createRule(t, dir, ".agents/rules/postgres-rule.md", "database: postgres", "PostgreSQL rule")
+				createRule(t, dir, ".agents/rules/mysql-rule.md", "database: mysql", "MySQL rule")
+				createRule(t, dir, ".agents/rules/generic-rule.md", "", "Generic rule")
+			},
+			taskName: "task-with-cmd",
+			wantErr:  false,
+			check: func(t *testing.T, result *Result) {
+				// Should include postgres-rule and generic-rule
+				// Should exclude mysql-rule
+				if len(result.Rules) != 2 {
+					t.Errorf("expected 2 rules, got %d", len(result.Rules))
+				}
+				foundPostgres := false
+				foundMySQL := false
+				for _, rule := range result.Rules {
+					if strings.Contains(rule.Content, "PostgreSQL rule") {
+						foundPostgres = true
+					}
+					if strings.Contains(rule.Content, "MySQL rule") {
+						foundMySQL = true
+					}
+				}
+				if !foundPostgres {
+					t.Error("expected to find PostgreSQL rule")
+				}
+				if foundMySQL {
+					t.Error("did not expect to find MySQL rule")
+				}
+			},
+		},
+		{
+			name: "command selectors combine with task selectors",
+			setup: func(t *testing.T, dir string) {
+				// Task has its own selectors
+				createTask(t, dir, "combined-selectors", "selectors:\n  env: production", "/enable-feature")
+				// Command also has selectors
+				createCommand(t, dir, "enable-feature", "selectors:\n  feature: auth", "Enabling authentication...")
+				// Rules with different combinations
+				createRule(t, dir, ".agents/rules/prod-auth-rule.md", "env: production\nfeature: auth", "Production auth rule")
+				createRule(t, dir, ".agents/rules/prod-rule.md", "env: production", "Production rule")
+				createRule(t, dir, ".agents/rules/auth-rule.md", "feature: auth", "Auth rule")
+				createRule(t, dir, ".agents/rules/dev-rule.md", "env: development", "Development rule")
+			},
+			taskName: "combined-selectors",
+			wantErr:  false,
+			check: func(t *testing.T, result *Result) {
+				// Should include: prod-auth-rule (matches both), prod-rule (matches env), auth-rule (matches feature)
+				// Should exclude: dev-rule (env doesn't match)
+				if len(result.Rules) != 3 {
+					t.Errorf("expected 3 rules, got %d", len(result.Rules))
+					for _, r := range result.Rules {
+						t.Logf("Found rule: %s", r.Content)
+					}
+				}
+			},
+		},
 	}
 
 	for _, tt := range tests {

pkg/codingcontext/markdown/frontmatter.go

@@ -77,6 +77,10 @@ type CommandFrontMatter struct {
 	// ExpandParams controls whether parameter expansion should occur
 	// Defaults to true if not specified
 	ExpandParams *bool `yaml:"expand,omitempty" json:"expand,omitempty"`
+
+	// Selectors contains additional custom selectors for filtering rules
+	// When a command is used in a task, its selectors are combined with task selectors
+	Selectors map[string]any `yaml:"selectors,omitempty" json:"selectors,omitempty"`
 }
 
 // UnmarshalJSON custom unmarshaler that populates both typed fields and Content map