{"id":34503359,"url":"https://github.com/kitproj/coding-context-cli","last_synced_at":"2026-01-29T00:18:06.992Z","repository":{"id":321672124,"uuid":"1086747704","full_name":"kitproj/coding-context-cli","owner":"kitproj","description":"Get the session context for a coding agent. ","archived":false,"fork":false,"pushed_at":"2026-01-17T04:38:20.000Z","size":13419,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T10:59:32.551Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://kitproj.github.io/coding-context-cli/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kitproj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-30T21:06:22.000Z","updated_at":"2026-01-16T22:18:11.000Z","dependencies_parsed_at":"2025-10-31T07:06:52.346Z","dependency_job_id":null,"html_url":"https://github.com/kitproj/coding-context-cli","commit_stats":null,"previous_names":["kitproj/coding-agent-context-cli","kitproj/coding-context-cli"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/kitproj/coding-context-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitproj%2Fcoding-context-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitproj%2Fcoding-context-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitproj%2Fcoding-context-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitproj%2Fcoding-context-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitproj","download_url":"https://codeload.github.com/kitproj/coding-context-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitproj%2Fcoding-context-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28857514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T22:56:21.783Z","status":"ssl_error","status_checked_at":"2026-01-28T22:56:00.861Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T02:30:30.714Z","updated_at":"2026-01-29T00:18:06.986Z","avatar_url":"https://github.com/kitproj.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Coding Agent Context CLI\n\nA command-line interface for dynamically assembling context for AI coding agents.\n\nThis 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.\n\n**📖 [View Full Documentation](https://kitproj.github.io/coding-context-cli/)**  \n**📋 [View Specification](./SPECIFICATION.md)** - The Coding Context Standard  \n**📊 [View Slide Deck](./SLIDES.md)** | [Download PDF](./SLIDES.pdf) | [How to Present](./SLIDES_README.md)\n\n## Generated Context Structure\n\nThe tool assembles context into a structured prompt with the following components:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Generated Coding Context Prompt                             │\n├─────────────────────────────────────────────────────────────┤\n│                                                               │\n│  ┌───────────────────────────────────────────────────────┐  │\n│  │ 1. Rules Content (Markdown)                           │  │\n│  │    • Coding standards and guidelines                  │  │\n│  │    • Team conventions and best practices              │  │\n│  │    • Filtered by selectors (-s flag)                  │  │\n│  │    • Skipped in resume mode (-r flag)                 │  │\n│  └───────────────────────────────────────────────────────┘  │\n│                                                               │\n│  ┌───────────────────────────────────────────────────────┐  │\n│  │ 2. Skills Metadata (XML) - Optional                   │  │\n│  │    • Available skills with names \u0026 descriptions       │  │\n│  │    • Progressive disclosure - full content on demand  │  │\n│  │    • Only included if skills are discovered           │  │\n│  └───────────────────────────────────────────────────────┘  │\n│                                                               │\n│  ┌───────────────────────────────────────────────────────┐  │\n│  │ 3. Task Content (Markdown)                            │  │\n│  │    • Task-specific instructions                       │  │\n│  │    • Parameter substitutions (${param})               │  │\n│  │    • Command expansions (!`command`)                  │  │\n│  │    • Path expansions (@file)                          │  │\n│  └───────────────────────────────────────────────────────┘  │\n│                                                               │\n└─────────────────────────────────────────────────────────────┘\n```\n\n**Key Points:**\n- **Rules**: Reusable context that applies across multiple tasks\n- **Skills**: Enable progressive disclosure of specialized capabilities\n- **Task Content**: Specific instructions for the current task with dynamic content expansion\n- **Note**: Task frontmatter is used for filtering and metadata but is not included in the output\n\n## Features\n\n- **Dynamic Context Assembly**: Merges context from various source files.\n- **Task-Specific Prompts**: Use different prompts for different tasks (e.g., `feature`, `bugfix`).\n- **Rule-Based Context**: Define reusable context snippets (rules) that can be included or excluded.\n- **Skills System**: Progressive disclosure of specialized capabilities via skill directories.\n- **Frontmatter Filtering**: Select rules based on metadata using frontmatter selectors (matches top-level YAML fields only).\n- **Bootstrap Scripts**: Run scripts to fetch or generate context dynamically.\n- **Parameter Substitution**: Inject values into your task prompts.\n- **Token Estimation**: Get an estimate of the total token count for the generated context.\n\n## Supported Coding Agents\n\nThis tool is compatible with configuration files from various AI coding agents and IDEs. **[View complete list of 35+ supported agents →](https://kitproj.github.io/coding-context-cli/reference/supported-agents)**\n\n### Primary Supported Agents (with dedicated `-a` flag)\n\n- **[GitHub Copilot](https://github.com/features/copilot)**: `.github/copilot-instructions.md`, `.github/agents` (`-a copilot`)\n- **[Anthropic Claude](https://claude.ai/)**: `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md` (`-a claude`)\n- **[Cursor](https://cursor.sh/)**: `.cursor/rules`, `.cursorrules` (`-a cursor`)\n- **[Google Gemini](https://gemini.google.com/)**: `GEMINI.md`, `.gemini/styleguide.md` (`-a gemini`)\n- **[Augment](https://augmentcode.com/)**: `.augment/rules`, `.augment/guidelines.md` (`-a augment`)\n- **[Windsurf](https://codeium.com/windsurf)**: `.windsurf/rules`, `.windsurfrules` (`-a windsurf`)\n- **[OpenCode.ai](https://opencode.ai/)**: `.opencode/agent`, `.opencode/command`, `.opencode/rules` (`-a opencode`)\n- **[Codex](https://codex.ai/)**: `AGENTS.md`, `.codex/AGENTS.md` (`-a codex`)\n\n### Additional Compatible Agents\n\n- **Codeium**, **Tabnine**, **Amazon Q Developer** (CodeWhisperer)\n- **Sourcegraph Cody**, **Continue**, **Aider**\n- **Replit Ghostwriter**, **GitLab Duo**\n- **All OpenAI models** (GPT-4, ChatGPT), **LLM APIs**\n- **Agent frameworks**: LangChain, AutoGPT, BabyAGI\n- **And 20+ more** - see [full documentation](https://kitproj.github.io/coding-context-cli/reference/supported-agents)\n\n### Generic AI Agent Support\n\n- **Generic AI Agents**: `AGENTS.md`, `.agents/rules`, `.agents/commands` (reusable content blocks), `.agents/tasks`\n\nThe tool automatically discovers and includes rules from these locations in your project and user home directory (`~`).\n\n## Agentic Workflows\n\nThis tool plays a crucial role in the **agentic workflow ecosystem** by providing rich, contextual information to AI agents. It complements systems like **GitHub Next's Agentic Workflows** by:\n\n- **Context Preparation**: Assembles rules, guidelines, and task-specific prompts before agent execution\n- **Workflow Integration**: Can be invoked in GitHub Actions to provide context to autonomous agents\n- **Dynamic Context**: Supports runtime parameters and bootstrap scripts for real-time information\n- **Multi-Stage Support**: Different context assemblies for planning, implementation, and validation stages\n\nFor a comprehensive guide on using this tool with agentic workflows, see [AGENTIC_WORKFLOWS.md](./AGENTIC_WORKFLOWS.md).\n\n## Installation\n\nYou 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.\n\n### Linux\n\n**AMD64:**\n```bash\nsudo curl -fsL -o /usr/local/bin/coding-context https://github.com/kitproj/coding-context-cli/releases/download/v0.0.34/coding-context_v0.0.34_linux_amd64\nsudo chmod +x /usr/local/bin/coding-context\n```\n\n**ARM64:**\n```bash\nsudo curl -fsL -o /usr/local/bin/coding-context https://github.com/kitproj/coding-context-cli/releases/download/v0.0.34/coding-context_v0.0.34_linux_arm64\nsudo chmod +x /usr/local/bin/coding-context\n```\n\n### MacOS\n\n**Intel (AMD64):**\n```bash\nsudo curl -fsL -o /usr/local/bin/coding-context https://github.com/kitproj/coding-context-cli/releases/download/v0.0.34/coding-context_v0.0.34_darwin_amd64\nsudo chmod +x /usr/local/bin/coding-context\n```\n\n**Apple Silicon (ARM64):**\n```bash\nsudo curl -fsL -o /usr/local/bin/coding-context https://github.com/kitproj/coding-context-cli/releases/download/v0.0.34/coding-context_v0.0.34_darwin_arm64\nsudo chmod +x /usr/local/bin/coding-context\n```\n\n## Usage\n\n```\nUsage:\n  coding-context [options] \u003ctask-name\u003e [user-prompt]\n\nArguments:\n  \u003ctask-name\u003e\n      The name of a task file to look up in task search paths (.agents/tasks).\n      Task files are matched by filename (without .md extension).\n  \n  [user-prompt] (optional)\n      Optional text to append to the task. It can contain slash commands\n      (e.g., '/command-name') which will be expanded, and parameter \n      substitution (${param}).\n\nOptions:\n  -C string\n    \tChange to directory before doing anything. (default \".\")\n  -d value\n    \tRemote directory containing rules and tasks. Can be specified multiple times. Supports various protocols via go-getter (http://, https://, git::, s3::, etc.).\n  -m string\n    \tGo Getter URL to a manifest file containing search paths (one per line). Every line is included as-is.\n  -p value\n    \tParameter to substitute in the prompt. Can be specified multiple times as key=value.\n  -r\tResume mode: skip outputting rules and select task with 'resume: true' in frontmatter.\n  -s value\n    \tInclude rules with matching frontmatter. Can be specified multiple times as key=value.\n    \tNote: Only matches top-level YAML fields in frontmatter.\n  -a string\n    \tTarget agent to use. Required when using -w to write rules to the agent's user rules path. Supported agents: cursor, opencode, copilot, claude, gemini, augment, windsurf, codex.\n  -w\tWrite rules to agent's config file and output only task to stdout. Requires agent (via task or -a flag).\n```\n\n### Examples\n\n**Basic usage with local files:**\n```bash\ncoding-context -p jira_issue_key=PROJ-1234 fix-bug | llm -m gemini-pro\n```\n\nThis command will:\n1. Find a task file named `fix-bug.md` in the task search paths.\n2. Find all rule files in the search paths.\n3. Filter the rules based on selectors.\n4. Execute any associated bootstrap scripts.\n5. Substitute `${jira_issue_key}` with `PROJ-1234` in the task prompt.\n6. Print the combined context (rules + task) to `stdout`.\n7. Pipe the output to another program (in this case, `llm`).\n\n**Using remote directories:**\n```bash\ncoding-context \\\n  -d git::https://github.com/company/shared-rules.git \\\n  -d s3::https://s3.amazonaws.com/my-bucket/coding-standards \\\n  fix-bug | llm -m gemini-pro\n```\n\nThis command will:\n1. Download remote directories using go-getter\n2. Search for rules and tasks in the downloaded directories\n3. Combine them with local rules and tasks\n4. Apply the same processing as with local files\n\nThe `-d` flag supports various protocols via go-getter:\n- `http://` and `https://` - HTTP/HTTPS URLs\n- `git::` - Git repositories  \n- `s3::` - S3 buckets\n- `file://` - Local file paths\n- And more (see go-getter documentation)\n\n### Content Expansion Features\n\nTask and rule content supports three types of dynamic expansion:\n\n1. **Parameter Expansion**: Use `${parameter_name}` syntax to substitute parameter values from `-p` flags\n   ```markdown\n   Issue: ${issue_key}\n   Description: ${description}\n   ```\n\n2. **Command Expansion**: Use `` !`command` `` syntax to execute shell commands and include their output\n   ```markdown\n   Current date: !`date +%Y-%m-%d`\n   Git branch: !`git rev-parse --abbrev-ref HEAD`\n   ```\n\n3. **Path Expansion**: Use `@path` syntax to include file contents\n   ```markdown\n   Current configuration:\n   @config.yaml\n   ```\n\n**Security Note:** All expansions are processed in a single pass to prevent injection attacks. Expanded content is never re-processed.\n\n### Example Tasks\n\nThe `\u003ctask-name\u003e` corresponds to the filename (without the `.md` extension) of task files. Here are some common examples:\n\n- `triage-bug`\n- `review-pull-request`\n- `fix-broken-build`\n- `migrate-java-version`\n- `enhance-docs`\n- `remove-feature-flag`\n- `speed-up-build`\n\nEach of these would have a corresponding `.md` file (e.g., `triage-bug.md`, `fix-broken-build.md`).\n\n## How It Works\n\nThe tool assembles the context in the following order:\n\n1.  **Rule Files**: It searches for rule files (`.md` or `.mdc`) in directories specified via `-d` flags and automatically-added working directory and home directory.\n2.  **Rule Bootstrap Scripts**: For each rule file found (e.g., `my-rule.md`), it looks for an executable script named `my-rule-bootstrap`. If found, it runs the script before processing the rule file. These scripts are meant for bootstrapping the environment (e.g., installing tools) and their output is sent to `stderr`, not into the main context.\n3.  **Filtering**: If `-s` (include) flag is used, it parses the YAML frontmatter of each rule file to decide whether to include it. Note that selectors can only match top-level YAML fields (e.g., `language: go`), not nested fields.\n4.  **Task Prompt**: It searches for a task file matching the filename (without `.md` extension). Tasks are matched by filename, not by `task_name` in frontmatter. If selectors are provided with `-s`, they are used to filter between multiple task files with the same filename.\n5.  **Task Bootstrap Script**: For the task file found (e.g., `fix-bug.md`), it looks for an executable script named `fix-bug-bootstrap`. If found, it runs the script before processing the task file. This allows task-specific environment setup or data preparation.\n6.  **User Prompt Appending**: If a user-prompt argument is provided, it is appended to the task content after a delimiter (`---`).\n7.  **Parameter Expansion**: It substitutes variables in the task prompt and user-prompt using the `-p` flags.\n8.  **Output**: It prints the content of all included rule files, followed by the expanded task prompt, to standard output.\n9.  **Token Count**: A running total of estimated tokens is printed to standard error.\n\n### File Search Paths\n\nThe tool automatically searches for task and rule files in various locations. For a complete reference, see the [Search Paths documentation](https://kitproj.github.io/coding-context-cli/reference/search-paths).\n\n**Common locations:**\n- `./.agents/tasks/*.md` - Task definitions\n- `./.agents/rules/` - Rule files  \n- `./.agents/commands/` - Reusable command blocks\n- `./.agents/skills/*/SKILL.md` - Specialized skills\n- Various agent-specific paths (`.cursor/`, `.github/`, `.opencode/`, etc.)\n- User-wide rules in `~/.agents/rules`, `~/.claude/`, `~/.codex/`, etc.\n\nSee the full [Search Paths Reference](https://kitproj.github.io/coding-context-cli/reference/search-paths) for the complete list of locations.\n\n### Remote File System Support\n\nThe tool supports loading rules and tasks from remote locations via HTTP/HTTPS URLs. This enables:\n\n- **Shared team guidelines**: Host coding standards on a central server\n- **Organization-wide rules**: Distribute common rules across multiple projects\n- **Version-controlled context**: Serve rules from Git repositories\n- **Dynamic rules**: Update shared rules without modifying individual repositories\n\n**Usage:**\n\n```bash\n# Clone a Git repository containing rules\ncoding-context -d git::https://github.com/company/shared-rules.git /fix-bug\n\n# Use multiple remote sources\ncoding-context \\\n  -d git::https://github.com/company/shared-rules.git \\\n  -d https://cdn.company.com/coding-standards \\\n  /deploy\n\n# Mix local and remote directories\ncoding-context \\\n  -d git::https://github.com/company/shared-rules.git \\\n  -s languages=go \\\n  /implement-feature\n```\n\n**Supported protocols (via go-getter):**\n- `http://` and `https://` - HTTP/HTTPS URLs (downloads tar.gz, zip, or directories)\n- `git::` - Git repositories (e.g., `git::https://github.com/user/repo.git`)\n- `s3::` - S3 buckets (e.g., `s3::https://s3.amazonaws.com/bucket/path`)\n- `file://` - Local file paths\n- And more - see [go-getter documentation](https://github.com/hashicorp/go-getter)\n\n**Important notes:**\n- Remote directories are downloaded to a temporary location\n- Bootstrap scripts work in downloaded directories\n- Downloaded directories are cleaned up after execution\n- Supports all standard directory structures (`.agents/rules`, `.agents/tasks`, etc.)\n\n**Example: Using a Git repository:**\n\n```bash\n# Use a specific branch or tag\ncoding-context \\\n  -d 'git::https://github.com/company/shared-rules.git?ref=v1.0' \\\n  /fix-bug\n\n# Use a subdirectory within the repo\ncoding-context \\\n  -d 'git::https://github.com/company/mono-repo.git//coding-standards' \\\n  /implement-feature\n```\n\n## File Formats\n\n### Task Files\n\nTask files are Markdown files located in task search directories (e.g., `.agents/tasks/`). Tasks are matched by filename (without the `.md` extension), not by frontmatter fields. The `task_name` field in frontmatter is optional metadata. Task files can contain variables for substitution and can use selectors in frontmatter to filter between multiple task files with the same filename in different locations.\n\n**Example (`.agents/tasks/fix-bug.md`):**\n```markdown\n# Task: Fix Bug in ${jira_issue_key}\n\nHere is the context for the bug. Please analyze the following files and provide a fix.\n```\n\n**Example with selectors for multiple prompts (`.agents/tasks/deploy-staging.md`):**\n```markdown\n---\nenvironment: staging\n---\n# Deploy to Staging\n\nDeploy the application to the staging environment with extra validation.\n```\n\n**Example for production (`.agents/tasks/deploy-prod.md`):**\n```markdown\n---\nenvironment: production\n---\n# Deploy to Production\n\nDeploy the application to production with all safety checks.\n```\n\nYou can then select the appropriate task using:\n```bash\n# Deploy to staging\ncoding-context -s environment=staging deploy\n\n# Deploy to production\ncoding-context -s environment=production deploy\n```\n\n#### Task Frontmatter Selectors\n\nTask 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.\n\n**Example (`.agents/tasks/implement-go-feature.md`):**\n```markdown\n---\nselectors:\n  languages: go\n  stage: implementation\n---\n# Implement Feature\n\nImplement the feature following Go best practices and implementation guidelines.\n```\n\nWhen you run this task, it automatically applies the selectors:\n```bash\n# This command automatically includes only rules with languages=go and stage=implementation\ncoding-context implement-feature\n```\n\n**Selectors support OR logic for the same key using arrays:**\n```markdown\n---\nselectors:\n  languages: [go, python]\n  stage: testing\n---\n```\n\nThis will include rules that match `(languages=go OR languages=python) AND stage=testing`.\n\n**Combining task selectors with command-line selectors:**\n\nSelectors from both the task frontmatter and command line are combined (additive):\n```bash\n# Task has: selectors.languages = go\n# Command adds: -s priority=high\n# Result: includes rules matching languages=go AND priority=high\ncoding-context -s priority=high implement-feature\n```\n\n### Parameter Expansion Control\n\nBy default, parameter expansion occurs in all task and rule content. You can disable this behavior using the `expand` frontmatter field.\n\n**Example (task with expansion disabled):**\n```yaml\n---\nexpand: false\n---\n\nIssue: ${issue_number}\nTitle: ${issue_title}\n```\n\nWhen `expand: false` is set, parameter placeholders like `${variable}` are preserved as-is in the output, rather than being replaced with values from `-p` flags.\n\n**Use cases:**\n- Passing templates to AI agents that handle their own parameter substitution\n- Preserving template syntax for later processing\n- Avoiding conflicts with other templating systems\n\nThe `expand` field works in:\n- Task files (`.agents/tasks/*.md`)\n- Command files (`.agents/commands/*.md`)\n- Rule files (`.agents/rules/*.md`)\n\n### Resume Mode\n\nResume mode is designed for continuing work on a task where you've already established context. When using the `-r` flag:\n\n1. **Rules are skipped**: All rule files are excluded from output, saving tokens and reducing context size\n2. **Resume-specific task prompts are selected**: Automatically adds `-s resume=true` selector to find task files with `resume: true` in their frontmatter\n\nThis is particularly useful in agentic workflows where an AI agent has already been primed with rules and is continuing work from a previous session.\n\n**The `-r` flag is shorthand for:**\n- Adding `-s resume=true` selector\n- Skipping all rules output\n\n**Example usage:**\n```bash\n# Initial task invocation (includes all rules, uses task with resume: false)\ncoding-context -s resume=false fix-bug | ai-agent\n\n# Resume the task (skips rules, uses task with resume: true)\ncoding-context -r fix-bug | ai-agent\n```\n\n**Example task files for resume mode:**\n\nInitial task (`.agents/tasks/fix-bug-initial.md`):\n```markdown\n---\nresume: false\n---\n# Fix Bug\n\nAnalyze the issue and implement a fix.\nFollow the coding standards and write tests.\n```\n\nResume task (`.agents/tasks/fix-bug-resume.md`):\n```markdown\n---\nresume: true\n---\n# Fix Bug - Continue\n\nContinue working on the bug fix.\nReview your previous work and complete remaining tasks.\n```\n\nWith this approach, you can have multiple task prompts for the same task name, differentiated by the `resume` frontmatter field. Use `-s resume=false` to select the initial task (with rules), or `-r` to select the resume task (without rules).\n\n### Rule Files\n\nRule files are Markdown (`.md`) or `.mdc` files, optionally with YAML frontmatter for filtering.\n\n**Example (`.agents/rules/backend.md`):**\n```markdown\n---\nlanguages:\n  - go\n---\n\n# Backend Coding Standards\n\n- All new code must be accompanied by unit tests.\n- Use the standard logging library.\n```\n\nTo include this rule only when working on Go code, you would use `-s languages=go`:\n\n```bash\ncoding-context -s languages=go fix-bug\n```\n\nThis will include all rules with `languages: [ go ]` in their frontmatter, excluding rules for other languages.\n\n**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`). The frontmatter field is `languages` (plural) with array format.\n\n**Example: Language-Specific Rules**\n\nYou can create multiple language-specific rule files:\n\n- `.agents/rules/python-standards.md` with `languages: [ python ]`\n- `.agents/rules/javascript-standards.md` with `languages: [ javascript ]`\n- `.agents/rules/go-standards.md` with `languages: [ go ]`\n\nThen select only the relevant rules:\n\n```bash\n# Work on Python code with Python-specific rules\ncoding-context -s languages=python fix-bug\n\n# Work on JavaScript code with JavaScript-specific rules\ncoding-context -s languages=javascript enhance-feature\n```\n\n**Language Values**\n\nWhen using language selectors, language values should be **lowercase** (e.g., `go`, `python`, `javascript`, `java`, `typescript`). The frontmatter field should be `languages` (plural) in array format:\n\n```yaml\n---\nlanguages:\n  - go\n  - python\n---\n```\n\n**Common languages (lowercase):**\n- `c`, `csharp` (C#), `cpp` (C++), `css`\n- `dart`, `elixir`, `go`, `haskell`, `html`\n- `java`, `javascript`, `kotlin`, `lua`, `markdown`\n- `objectivec` (Objective-C), `php`, `python`, `ruby`, `rust`\n- `scala`, `shell`, `swift`, `typescript`, `yaml`\n\n**Note:** Language values should be lowercase in frontmatter and selectors.\n\n**Note:** Frontmatter selectors can only match top-level YAML fields. For example:\n- ✅ Works: `languages: [ go ]` matches `-s languages=go`\n- ❌ Doesn't work: Nested fields like `metadata.version: 1.0` cannot be matched with `-s metadata.version=1.0`\n\nIf you need to filter on nested data, flatten your frontmatter structure to use top-level fields only.\n\n**MCP Server Configuration**\n\nRules can optionally specify MCP (Model Context Protocol) server configurations for integration with AI coding agents. This is useful for defining server processes that AI agents can interact with.\n\n```yaml\n---\nlanguages:\n  - python\nmcp_server:\n  command: python\n  args: [\"-m\", \"server\"]\n  env:\n    PYTHON_PATH: /usr/bin/python3\n---\n```\n\nFor detailed information on MCP server configuration, see the [File Formats Reference](https://kitproj.github.io/coding-context-cli/reference/file-formats#mcp_server-rule-metadata).\n\n### Targeting a Specific Agent\n\nThe `-a` flag specifies which AI coding agent you're using. This information is currently used for:\n\n1. **Write Rules Mode**: With the `-w` flag, determines where to write rules (e.g., `~/.github/agents/AGENTS.md` for `copilot`)\n\n\u003e **Note:** Agent-based rule filtering is not currently implemented. All rules are included regardless of the `-a` value.\n\n**Supported agents:**\n- `cursor` - Cursor IDE\n- `opencode` - OpenCode.ai  \n- `copilot` - GitHub Copilot\n- `claude` - Anthropic Claude\n- `gemini` - Google Gemini\n- `augment` - Augment\n- `windsurf` - Windsurf\n- `codex` - Codex\n\n**Example:**\n\n```bash\n# Use with write rules mode\ncoding-context -a copilot -w fix-bug\n```\n\n**How it works:**\n- The `-a` flag sets the target agent value\n- The agent value is stored in the context for use by the `-w` flag\n- With `-w`, the agent determines where to write rules to the user's home directory\n- All rules are currently included regardless of agent value\n\n**Agent field in task frontmatter:**\n\nTasks can specify an `agent` field in their frontmatter, which overrides the `-a` command-line flag:\n\n```markdown\n---\nagent: cursor\n---\n# This task automatically sets the agent to cursor\n```\n\nThis is useful for tasks designed for specific agents, ensuring the correct agent is set for determining the write path with `-w`.\n\n### Bootstrap Scripts\n\nA bootstrap script is an executable file that has the same name as a rule or task file but with a `-bootstrap` suffix. These scripts are used to prepare the environment, for example by installing necessary tools. The output of these scripts is sent to `stderr` and is not part of the AI context.\n\n**Examples:**\n- Rule file: `.agents/rules/jira.md`\n- Rule bootstrap script: `.agents/rules/jira-bootstrap`\n- Task file: `.agents/tasks/fix-bug.md`\n- Task bootstrap script: `.agents/tasks/fix-bug-bootstrap`\n\nBootstrap scripts are executed in the following order:\n1. Rule bootstrap scripts run before their corresponding rule files are processed\n2. Task bootstrap scripts run after all rules are processed but before the task content is emitted\n\n**`.agents/rules/jira-bootstrap`:**\n```bash\n#!/bin/bash\n# This script installs the jira-cli if it's not already present.\nif ! command -v jira-cli \u0026\u003e /dev/null\nthen\n    echo \"Installing jira-cli...\" \u003e\u00262\n    # Add installation commands here\nfi\n```\n\n**`.agents/tasks/fix-bug-bootstrap`:**\n```bash\n#!/bin/bash\n# This script fetches the latest issue details before the task runs.\necho \"Fetching issue information...\" \u003e\u00262\n# Fetch and prepare issue data\n```\n\n### Command Files (Slash Commands)\n\nCommand files are reusable content blocks that can be referenced from task files using slash command syntax (e.g., `/command-name`). They enable modular, composable task definitions.\n\n**Example command file (`.agents/commands/pre-deploy.md`):**\n```markdown\n---\nexpand: true\n---\n# Pre-deployment Checklist\n\nRun tests: !`npm test`\nBuild status: !`git status`\n```\n\n**Using commands in a task (`.agents/tasks/deploy.md`):**\n```markdown\n# Deployment Task\n\n/pre-deploy\n\nDeploy the application to ${environment}.\n\n/post-deploy\n```\n\nCommands can also receive inline parameters:\n```markdown\n/greet name=\"Alice\"\n/deploy env=\"production\" version=\"1.2.3\"\n```\n\n### Skill Files\n\nSkill files provide specialized capabilities with progressive disclosure. Skills are discovered in `.agents/skills/` directories and each skill is a subdirectory containing a `SKILL.md` file with metadata.\n\n**Skills enable:**\n- **Progressive Disclosure**: Only skill metadata (name, description) is included in the initial context\n- **On-Demand Loading**: AI agents can load full skill content when needed\n- **Modular Capabilities**: Organize domain-specific knowledge separately from general rules\n- **Selector Filtering**: Skills can be filtered using selectors just like rules\n\n**Example skill structure:**\n```\n.agents/skills/\n├── data-analysis/\n│   └── SKILL.md\n└── pdf-processing/\n    └── SKILL.md\n```\n\n**Example skill file (`.agents/skills/data-analysis/SKILL.md`):**\n```markdown\n---\nname: data-analysis\ndescription: Analyze datasets, generate charts, and create summary reports. Use when the user needs to work with CSV, Excel, or other tabular data formats.\nlicense: MIT\nmetadata:\n  author: team-name\n  version: \"1.0\"\n---\n\n# Data Analysis\n\n## When to use this skill\nUse this skill when the user needs to:\n- Analyze CSV or Excel files\n- Generate charts and visualizations\n- Calculate statistics and summaries\n\n## How to analyze data\n1. Use pandas for data analysis:\n   ```python\n   import pandas as pd\n   df = pd.read_csv('data.csv')\n   ```\n```\n\n**Skill Frontmatter Fields:**\n- `name` (required): Skill identifier, 1-64 characters\n- `description` (required): What the skill does and when to use it, 1-1024 characters\n- `license` (optional): License applied to the skill\n- `compatibility` (optional): Environment requirements, max 500 characters\n- `metadata` (optional): Arbitrary key-value pairs\n\n**XML Output:**\nSkills are output as XML for easy parsing by AI agents:\n```xml\n\u003cavailable_skills\u003e\n  \u003cskill\u003e\n    \u003cname\u003edata-analysis\u003c/name\u003e\n    \u003cdescription\u003eAnalyze datasets, generate charts...\u003c/description\u003e\n    \u003clocation\u003e/path/to/.agents/skills/data-analysis/SKILL.md\u003c/location\u003e\n  \u003c/skill\u003e\n\u003c/available_skills\u003e\n```\n\nThe AI agent can then read the full skill content from the provided location when needed.\n\n### Task Frontmatter\n\nTask frontmatter contains metadata used for filtering, agent selection, and workflow automation. While the frontmatter itself is not included in the generated output, it serves important purposes:\n\n**What frontmatter is used for:**\n- **Task selection**: Filtering between multiple task files using selectors\n- **Agent specification**: The `agent` field can override the `-a` command-line flag\n- **Rule filtering**: The `selectors` field automatically filters rules without requiring explicit `-s` flags\n- **Workflow control**: Fields like `resume` control task behavior in different modes\n\n**Example usage:**\n```bash\ncoding-context -p issue_number=123 fix-bug\n```\n\n**Example task file:**\n```markdown\n---\nresume: false\nselectors:\n  languages: go\n  stage: implementation\n---\n# Fix Bug Task\n\nFix the bug in issue #${issue_number}...\n```\n\n**Output format:**\nThe task frontmatter is NOT included in the output. Only the task content (below the frontmatter delimiters) is included:\n```markdown\n# Fix Bug Task\n\nFix the bug in issue #123...\n```\n\nThis design keeps the output focused on actionable content while still allowing frontmatter to control behavior and filtering.\n\n**Example with selectors in frontmatter:**\n```bash\ncoding-context implement-feature\n```\n\nIf the task has `selectors` in its frontmatter, they will automatically filter rules, but the frontmatter itself won't appear in the output:\n```markdown\n# Implementation Task\n...\n```\n\n## Presentations\n\nA comprehensive slide deck is available for presenting and learning about the Coding Context CLI:\n\n- **[View Slide Deck](./SLIDES.md)** - Full presentation with 50+ slides\n- **[Presentation Guide](./SLIDES_README.md)** - How to view, export, and present\n- **[Example Usage](./examples/PRESENTATION.md)** - Presentation scenarios and tips\n\nThe slides are written in [Marp](https://marp.app/) format and can be:\n- Viewed in VS Code with the Marp extension\n- Exported to HTML, PDF, or PowerPoint\n- Presented directly from a browser\n- Customized for your audience\n\nPerfect for:\n- **Team onboarding** - Introduce the tool to new team members\n- **Tech talks** - Present at meetups or conferences\n- **Workshops** - Run hands-on training sessions\n- **Documentation** - Visual reference for features\n\n## Troubleshooting\n\n### Common Issues\n\n**Task not found**\n- Verify the task file exists in `.agents/tasks/` with the correct filename\n- Tasks are matched by filename (without `.md` extension), not by `task_name` in frontmatter\n- Check that you're using the correct task name: `coding-context fix-bug` (not `/fix-bug`)\n\n**No rules included**\n- Check that rule files exist in search paths (`.agents/rules/`, etc.)\n- Verify selector syntax: use `-s languages=go` (not `-p languages=go`)\n- Remember: `-s` filters rules, `-p` substitutes parameters\n- Rules without frontmatter are always included (unless using resume mode)\n\n**Parameters not substituted**\n- Ensure you're using `-p` flag: `coding-context -p issue=123 fix-bug`\n- Check parameter names match exactly (case-sensitive): `${issue_key}` matches `-p issue_key=...`\n- Verify the task file uses `${parameter}` syntax\n\n**Wrong rules included**\n- Check frontmatter spelling and case sensitivity\n- Use `languages:` (plural) in frontmatter and `-s languages=go` in selectors\n- All selectors must match (AND logic): `-s languages=go -s stage=testing`\n\n**Bootstrap script not running**\n- Make the script executable: `chmod +x .agents/rules/my-rule-bootstrap`\n- Name it correctly: `{rule-filename}-bootstrap` (e.g., `jira-context-bootstrap` for `jira-context.md`)\n- Check script output in stderr\n\nFor more help, see the [full documentation](https://kitproj.github.io/coding-context-cli/) or [open an issue](https://github.com/kitproj/coding-context-cli/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitproj%2Fcoding-context-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitproj%2Fcoding-context-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitproj%2Fcoding-context-cli/lists"}