Extract core functionality into embeddable context package with visitor pattern

.gitignore

@@ -1,3 +1,11 @@
 # Binary output
 coding-context
 coding-context-cli
+
+# Example binaries
+examples/*/basic
+examples/*/*
+!examples/*/*.go
+!examples/*/*.md
+examples/*/visitor
+examples/*/basic

README.md

@@ -1,6 +1,6 @@
 # Coding Agent Context CLI
 
-A command-line interface for dynamically assembling context for AI coding agents.
+A command-line interface and embeddable library for dynamically assembling context for AI coding agents.
 
 This tool collects context from predefined rule files and a task-specific prompt, substitutes parameters, and prints a single, combined context to standard output. This is useful for feeding a large amount of relevant information into an AI model like Claude, Gemini, or OpenAI's GPT series.
 
@@ -13,6 +13,7 @@ This tool collects context from predefined rule files and a task-specific prompt
 - **Bootstrap Scripts**: Run scripts to fetch or generate context dynamically.
 - **Parameter Substitution**: Inject values into your task prompts.
 - **Token Estimation**: Get an estimate of the total token count for the generated context.
+- **Embeddable Library**: Use as a Go library in your own applications (see [context package documentation](./context/README.md)).
 
 ## Supported Coding Agents
 
@@ -32,6 +33,8 @@ The tool automatically discovers and includes rules from these locations in your
 
 ## Installation
 
+### CLI Tool
+
 You can install the CLI by downloading the latest release from the [releases page](https://github.com/kitproj/coding-context-cli/releases) or by building from source.
 
 ```bash
@@ -40,8 +43,20 @@ sudo curl -fsL -o /usr/local/bin/coding-context-cli https://github.com/kitproj/c
 sudo chmod +x /usr/local/bin/coding-context-cli
 ```
 
+### Go Library
+
+To use this as a library in your Go application:
+
+```bash
+go get github.com/kitproj/coding-context-cli/context
+```
+
+See the [context package documentation](./context/README.md) for detailed usage examples.
+
 ## Usage
 
+### Command Line
+
 ```
 Usage:
   coding-context-cli [options] <task-name>
@@ -84,6 +99,46 @@ The `<task-name>` is the name of the task you want the agent to perform. Here ar
 
 Each of these would have a corresponding `.md` file in a `tasks` directory (e.g., `triage-bug.md`).
 
+### Library Usage
+
+You can also use this tool as a library in your Go applications. Here's a simple example:
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	ctxlib "github.com/kitproj/coding-context-cli/context"
+)
+
+func main() {
+	// Create parameters for substitution
+	params := make(ctxlib.ParamMap)
+	params["component"] = "auth"
+	params["issue"] = "login bug"
+
+	// Configure the assembler
+	config := ctxlib.Config{
+		WorkDir:  ".",
+		TaskName: "fix-bug",
+		Params:   params,
+	}
+
+	// Assemble the context
+	assembler := ctxlib.NewAssembler(config)
+	ctx := context.Background()
+	if err := assembler.Assemble(ctx); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
+```
+
+For more detailed library usage examples, see the [context package documentation](./context/README.md).
+
 ## How It Works
 
 The tool assembles the context in the following order:

context/README.md

@@ -0,0 +1,274 @@
+# Context Package
+
+The `context` package provides a library for dynamically assembling context for AI coding agents. This package can be embedded in other Go applications to programmatically collect and assemble context from various rule files and task prompts.
+
+## Overview
+
+The context package extracts the core functionality from the `coding-context-cli` tool, making it reusable as a library. It allows you to:
+
+- Assemble context from rule files and task prompts
+- Filter rules based on frontmatter metadata
+- Substitute parameters in task prompts
+- Run bootstrap scripts before processing rules
+- Estimate token counts for the assembled context
+
+## Installation
+
+```bash
+go get github.com/kitproj/coding-context-cli/context
+```
+
+## Quick Start
+
+Here's a simple example of using the context package:
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	ctxlib "github.com/kitproj/coding-context-cli/context"
+)
+
+func main() {
+	// Create parameters for substitution
+	params := make(ctxlib.ParamMap)
+	params["component"] = "auth"
+	params["issue"] = "login bug"
+
+	// Create selectors for filtering rules
+	selectors := make(ctxlib.SelectorMap)
+	selectors["language"] = "go"
+
+	// Configure the assembler
+	config := ctxlib.Config{
+		WorkDir:   ".",
+		TaskName:  "fix-bug",
+		Params:    params,
+		Selectors: selectors,
+	}
+
+	// Create the assembler
+	assembler := ctxlib.NewAssembler(config)
+
+	// Assemble the context
+	ctx := context.Background()
+	if err := assembler.Assemble(ctx); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
+```
+
+## Core Types
+
+### Config
+
+`Config` holds the configuration for context assembly:
+
+```go
+type Config struct {
+	// WorkDir is the working directory to use
+	WorkDir string
+
+	// TaskName is the name of the task to execute
+	TaskName string
+
+	// Params are parameters for substitution in task prompts
+	Params ParamMap
+
+	// Selectors are frontmatter selectors for filtering rules
+	Selectors SelectorMap
+
+	// Stdout is where assembled context is written (defaults to os.Stdout)
+	Stdout io.Writer
+
+	// Stderr is where progress messages are written (defaults to os.Stderr)
+	Stderr io.Writer
+
+	// Visitor is called for each selected rule (defaults to DefaultRuleVisitor)
+	Visitor RuleVisitor
+}
+```
+
+### Assembler
+
+`Assembler` assembles context from rule and task files:
+
+```go
+// Create a new assembler
+assembler := context.NewAssembler(config)
+
+// Assemble the context
+err := assembler.Assemble(ctx)
+```
+
+### ParamMap
+
+`ParamMap` represents a map of parameters for substitution in task prompts:
+
+```go
+params := make(context.ParamMap)
+params["key"] = "value"
+
+// Or use the Set method (useful for flag parsing)
+params.Set("key=value")
+```
+
+### SelectorMap
+
+`SelectorMap` is used for filtering rules based on frontmatter metadata:
+
+```go
+selectors := make(context.SelectorMap)
+selectors["language"] = "go"
+selectors["environment"] = "production"
+
+// Or use the Set method (useful for flag parsing)
+selectors.Set("language=go")
+```
+
+## Utility Functions
+
+### ParseMarkdownFile
+
+Parse a markdown file with YAML frontmatter:
+
+```go
+var frontmatter map[string]string
+content, err := context.ParseMarkdownFile("path/to/file.md", &frontmatter)
+```
+
+### EstimateTokens
+
+Estimate the number of LLM tokens in text:
+
+```go
+tokens := context.EstimateTokens("This is some text")
+```
+
+### RuleVisitor (Visitor Pattern)
+
+The `RuleVisitor` interface allows you to customize how rules are processed as they are selected. This enables advanced use cases like logging, filtering, transformation, or custom output formatting.
+
+```go
+type RuleVisitor interface {
+	// VisitRule is called for each rule that matches the selection criteria
+	VisitRule(ctx context.Context, rule *Document) error
+}
+```
+
+The `Document` type represents both rules and tasks (they share the same structure):
+
+```go
+type Frontmatter map[string]string
+
+type Document struct {
+	Path        string      // Absolute path to the file
+	Content     string      // Parsed content (without frontmatter)
+	Frontmatter Frontmatter // YAML frontmatter metadata
+	Tokens      int         // Estimated token count
+}
+```
+
+**Example: Custom Visitor**
+
+```go
+// CustomVisitor collects rule metadata
+type CustomVisitor struct {
+	Rules []*context.Document
+}
+
+func (v *CustomVisitor) VisitRule(ctx context.Context, rule *context.Document) error {
+	// Custom processing logic
+	v.Rules = append(v.Rules, rule)
+	fmt.Printf("Processing rule: %s (%d tokens)\n", rule.Path, rule.Tokens)
+	return nil
+}
+
+// Use the custom visitor
+visitor := &CustomVisitor{}
+assembler := context.NewAssembler(context.Config{
+	WorkDir:  ".",
+	TaskName: "my-task",
+	Visitor:  visitor,
+})
+```
+
+By default, the `DefaultRuleVisitor` is used, which writes rule content to stdout and logs progress to stderr.
+
+## Advanced Usage
+
+### Custom Output Writers
+
+You can redirect the output to custom writers:
+
+```go
+var stdout, stderr bytes.Buffer
+
+config := context.Config{
+	WorkDir:   ".",
+	TaskName:  "my-task",
+	Params:    make(context.ParamMap),
+	Selectors: make(context.SelectorMap),
+	Stdout:    &stdout,  // Assembled context goes here
+	Stderr:    &stderr,  // Progress messages go here
+}
+
+assembler := context.NewAssembler(config)
+err := assembler.Assemble(ctx)
+
+// Now you can process the output
+contextContent := stdout.String()
+progressMessages := stderr.String()
+```
+
+### Context Cancellation
+
+The `Assemble` method respects context cancellation:
+
+```go
+ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+defer cancel()
+
+assembler := context.NewAssembler(config)
+err := assembler.Assemble(ctx)
+```
+
+## File Search Paths
+
+The assembler searches for task and rule files in predefined locations:
+
+**Tasks:**
+- `./.agents/tasks/<task-name>.md`
+- `~/.agents/tasks/<task-name>.md`
+- `/etc/agents/tasks/<task-name>.md`
+
+**Rules:**
+The tool searches for various files and directories, including:
+- `CLAUDE.local.md`
+- `.agents/rules`, `.cursor/rules`, `.augment/rules`, `.windsurf/rules`
+- `.opencode/agent`, `.opencode/command`
+- `.github/copilot-instructions.md`, `.gemini/styleguide.md`
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` (and in parent directories)
+- User-specific rules in `~/.agents/rules`, `~/.claude/CLAUDE.md`, etc.
+- System-wide rules in `/etc/agents/rules`, `/etc/opencode/rules`
+
+## Bootstrap Scripts
+
+Bootstrap scripts are executed before processing rule files. If a rule file `setup.md` exists, the assembler will look for `setup-bootstrap` and execute it if found. This is useful for environment setup or tool installation.
+
+## Testing
+
+The package includes comprehensive tests. Run them with:
+
+```bash
+go test github.com/kitproj/coding-context-cli/context
+```
+
+## License
+
+This package is part of the coding-context-cli project and follows the same license.