From 8333757a8bda2d6aae96a7129d0b49aa47a67ccc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Dec 2025 23:37:37 +0000 Subject: [PATCH 1/5] Initial plan From 488d9598ecfe0c7a30d7f6dabaa792e81c92ea31 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Dec 2025 23:42:43 +0000 Subject: [PATCH 2/5] Fix task frontmatter documentation - NOT included in output Co-authored-by: alexec <1142830+alexec@users.noreply.github.com> --- docs/how-to/create-tasks.md | 13 +++++-------- docs/how-to/use-selectors.md | 18 +++++++++--------- docs/reference/cli.md | 18 +++++++----------- docs/reference/file-formats.md | 7 +++++-- 4 files changed, 26 insertions(+), 30 deletions(-) diff --git a/docs/how-to/create-tasks.md b/docs/how-to/create-tasks.md index b88e8d5..d979d43 100644 --- a/docs/how-to/create-tasks.md +++ b/docs/how-to/create-tasks.md @@ -171,24 +171,21 @@ coding-context -s priority=high implement-feature ## Task Frontmatter -Task frontmatter is **always** automatically included in the output when present. This happens automatically - no flag is needed. This is useful when downstream tools need access to task metadata. +Task frontmatter is used for filtering and metadata purposes but is **NOT included in the output**. The frontmatter controls behavior (like auto-filtering rules via the `selectors` field) but only the task content below the frontmatter delimiters is included in the assembled context. **Example:** ```bash coding-context implement-feature ``` -**Output:** -```yaml ---- -selectors: - languages: go - stage: implementation ---- +**Output (frontmatter NOT included):** +```markdown # Implement Feature in Go ... ``` +The frontmatter (with `selectors`, `languages`, etc.) is parsed and used to filter rules and control behavior, but it does not appear in the final output sent to the AI agent. + ## Best Practices 1. **Use descriptive task names**: Make them clear and specific diff --git a/docs/how-to/use-selectors.md b/docs/how-to/use-selectors.md index 9221fb7..35bf1bb 100644 --- a/docs/how-to/use-selectors.md +++ b/docs/how-to/use-selectors.md @@ -203,22 +203,22 @@ coding-context -s environment=production deploy ### Viewing Task Frontmatter -Task frontmatter (including selectors) is automatically included in the output: +Task frontmatter (including selectors) is used for filtering and metadata but is **NOT included in the output**. Only the task content appears in the final assembled context. ```bash coding-context implement-feature ``` -**Output:** -```yaml ---- -selectors: - languages: go - stage: implementation ---- -# Task content... +**Output (frontmatter NOT included):** +```markdown +# Implement Feature in Go + +Implement the feature following Go best practices and implementation guidelines. +... ``` +The frontmatter controls which rules are selected but does not appear in the output sent to the AI agent. + ## Understanding Selector Matching **Rules are included if:** diff --git a/docs/reference/cli.md b/docs/reference/cli.md index b5de58a..852ae41 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -316,20 +316,18 @@ This mode is particularly useful when working with AI coding agents that read ru ### Standard Output (stdout) The assembled context, consisting of: -1. Task frontmatter (YAML format) - always included when task has frontmatter +1. All matching rule files (content only, without frontmatter) 2. Available skills metadata (XML format) - included when skills are discovered -3. All matching rule files -4. The selected task prompt (with parameters substituted) +3. The selected task content (with parameters substituted, without frontmatter) -Task frontmatter is automatically included at the beginning of the output when present. This includes all frontmatter fields such as `task_name`, `selectors`, `resume`, `language`, `agent`, and any custom fields. +**Note:** Task frontmatter is used for filtering and metadata but is **NOT included in the output**. Only the task content below the frontmatter delimiters appears in the final output. -Skills metadata (when present) is output as XML after the task frontmatter and before rules, listing available skills for progressive disclosure. +Skills metadata (when present) is output as XML after rules and before the task content, listing available skills for progressive disclosure. **Example output:** -```yaml ---- -resume: false ---- +```markdown +# Rule content here... + data-analysis @@ -338,8 +336,6 @@ resume: false -# Rule content here... - # Fix Bug Task ... ``` diff --git a/docs/reference/file-formats.md b/docs/reference/file-formats.md index 4e1dc40..47eed71 100644 --- a/docs/reference/file-formats.md +++ b/docs/reference/file-formats.md @@ -25,18 +25,21 @@ Task files define what the AI agent should do. They are Markdown files with YAML Content can include ${parameter_placeholders}. ``` -**Note:** The `task_name` field is optional. Tasks are matched by filename (without `.md` extension), not by `task_name` in frontmatter. The `task_name` field is useful for metadata and appears in the frontmatter output. +**Note:** The `task_name` field is optional. Tasks are matched by filename (without `.md` extension), not by `task_name` in frontmatter. The `task_name` field is useful for metadata but task frontmatter is **NOT included in the output** - only the task content below the frontmatter delimiters appears in the final assembled context. ### Frontmatter Fields #### `task_name` (optional) **Type:** String -**Purpose:** Metadata field that identifies the task. Tasks are actually matched by filename (without `.md` extension), not by this field. This field is useful for metadata and can be used in task frontmatter output. +**Purpose:** Metadata field that identifies the task. Tasks are matched by filename (without `.md` extension), not by this field. This field is metadata only. + +**Important:** Task frontmatter is **NOT included in the output** - only the task content below the frontmatter delimiters appears in the final assembled context. **Example:** ```yaml --- +task_name: fix-bug --- ``` From 020b54a5c666720646b5c06e4f29b6212e6ae34a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Dec 2025 23:44:00 +0000 Subject: [PATCH 3/5] Standardize to 'languages' (plural) throughout documentation Co-authored-by: alexec <1142830+alexec@users.noreply.github.com> --- SPECIFICATION.md | 13 +++++++------ docs/how-to/create-rules.md | 2 +- docs/how-to/use-selectors.md | 2 +- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/SPECIFICATION.md b/SPECIFICATION.md index ddb4dd2..4d31878 100644 --- a/SPECIFICATION.md +++ b/SPECIFICATION.md @@ -766,7 +766,7 @@ Selectors filter rules and tasks based on frontmatter metadata, enabling context **Command-line:** ```bash -s key=value --s language=go +-s languages=go -s stage=implementation ``` @@ -774,7 +774,7 @@ Selectors filter rules and tasks based on frontmatter metadata, enabling context ```yaml --- selectors: - language: go + languages: go stage: implementation --- ``` @@ -785,10 +785,11 @@ selectors: ```yaml # Rule frontmatter --- -language: go +languages: + - go --- -# Selector: -s language=go +# Selector: -s languages=go # Result: ✅ Match ``` @@ -810,8 +811,8 @@ languages: **Multiple selectors (AND logic):** ```bash -# Requires: language=go AND stage=implementation --s language=go -s stage=implementation +# Requires: languages=go AND stage=implementation +-s languages=go -s stage=implementation ``` **OR logic (task frontmatter):** diff --git a/docs/how-to/create-rules.md b/docs/how-to/create-rules.md index 0c4fed8..ae0567c 100644 --- a/docs/how-to/create-rules.md +++ b/docs/how-to/create-rules.md @@ -192,7 +192,7 @@ coding-context -s source=jira fix-bug ## Common Language Values -Use lowercase values in your `language:` frontmatter: +Use lowercase values in your `languages:` frontmatter: - c, c++, c#, css - dart, elixir, go diff --git a/docs/how-to/use-selectors.md b/docs/how-to/use-selectors.md index 35bf1bb..c59def2 100644 --- a/docs/how-to/use-selectors.md +++ b/docs/how-to/use-selectors.md @@ -159,7 +159,7 @@ Use arrays for OR logic within the same selector key: ```markdown --- selectors: - language: [go, python, javascript] + languages: [go, python, javascript] stage: refactoring --- ``` From 280947fc640a88fc654dcbd57d82ca476eb6868e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Dec 2025 23:46:11 +0000 Subject: [PATCH 4/5] Reduce duplication and improve getting started guide Co-authored-by: alexec <1142830+alexec@users.noreply.github.com> --- README.md | 31 ++++++++++----------------- docs/tutorials/getting-started.md | 35 ++++++++++++++++--------------- 2 files changed, 29 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index fb11ebc..c8ed2d6 100644 --- a/README.md +++ b/README.md @@ -258,26 +258,17 @@ The tool assembles the context in the following order: ### File Search Paths -The tool looks for task and rule files in the following locations, in order of precedence: - -**Tasks:** -- `./.agents/tasks/*.md` (task name matches filename without `.md` extension) - -**Commands** (reusable content blocks referenced via slash commands like `/command-name` inside task content): -- `./.agents/commands/*.md` -- `./.cursor/commands/*.md` -- `./.opencode/command/*.md` - -**Skills** (specialized capabilities with progressive disclosure): -- `./.agents/skills/*/SKILL.md` (each subdirectory in `.agents/skills/` can contain a `SKILL.md` file) - -**Rules:** -The tool searches for a variety of files and directories, including: -- `CLAUDE.local.md` -- `.agents/rules`, `.cursor/rules`, `.augment/rules`, `.windsurf/rules`, `.opencode/agent` -- `.github/copilot-instructions.md`, `.github/agents`, `.gemini/styleguide.md`, `.augment/guidelines.md` -- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules` -- User-specific rules in `~/.agents/rules`, `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.opencode/rules`, etc. +The 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). + +**Common locations:** +- `./.agents/tasks/*.md` - Task definitions +- `./.agents/rules/` - Rule files +- `./.agents/commands/` - Reusable command blocks +- `./.agents/skills/*/SKILL.md` - Specialized skills +- Various agent-specific paths (`.cursor/`, `.github/`, `.opencode/`, etc.) +- User-wide rules in `~/.agents/rules`, `~/.claude/`, `~/.codex/`, etc. + +See the full [Search Paths Reference](https://kitproj.github.io/coding-context-cli/reference/search-paths) for the complete list of locations. ### Remote File System Support diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index f47b454..26a5384 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -24,20 +24,17 @@ This tutorial will guide you through your first steps with the Coding Context CL ## Step 1: Install the CLI -First, download and install the Coding Context CLI: +Follow the installation instructions in the main [README](https://github.com/kitproj/coding-context-cli#installation) or use the quick install command for your platform: +**Linux (AMD64):** ```bash -# For Linux sudo curl -fsL -o /usr/local/bin/coding-context \ https://github.com/kitproj/coding-context-cli/releases/download/v0.0.23/coding-context_v0.0.23_linux_amd64 sudo chmod +x /usr/local/bin/coding-context - -# For macOS -sudo curl -fsL -o /usr/local/bin/coding-context \ - https://github.com/kitproj/coding-context-cli/releases/download/v0.0.23/coding-context_v0.0.23_darwin_amd64 -sudo chmod +x /usr/local/bin/coding-context ``` +**macOS (Intel or Apple Silicon):** See [README installation section](https://github.com/kitproj/coding-context-cli#installation) + Verify the installation: ```bash @@ -83,8 +80,7 @@ EOF ``` **What this does:** -- The file is named `fix-bug.md`, which is how you'll reference it: `/fix-bug` -- The frontmatter (`---` section) includes `task_name: fix-bug` as metadata (optional) +- The file is named `fix-bug.md`, which is how you'll reference it: `fix-bug` (without the `.md` extension) - The `${issue_key}` and `${description}` are placeholders that will be replaced with actual values - The content provides instructions for the AI agent @@ -128,15 +124,20 @@ coding-context \ -p issue_key=BUG-123 \ -p description="Application crashes on startup" \ -s languages=go \ - /fix-bug + fix-bug ``` +**Understanding the flags:** +- **`-p` (parameters)**: Substitutes values into task content placeholders like `${issue_key}` +- **`-s` (selectors)**: Filters which rules to include based on frontmatter fields like `languages: [ go ]` + **What this command does:** -- `-p issue_key=BUG-123` replaces `${issue_key}` in the task -- `-p description="..."` replaces `${description}` in the task -- `-s languages=go` includes only rules with `languages: [ go ]` in frontmatter -- `/fix-bug` is the task name to use (slash indicates task file lookup) -- **Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`) +- `-p issue_key=BUG-123` replaces `${issue_key}` in the task content +- `-p description="..."` replaces `${description}` in the task content +- `-s languages=go` includes only rules with `languages: [ go ]` in their frontmatter +- `fix-bug` is the task filename to use (matches `fix-bug.md`) + +**Note:** Language values should be lowercase (e.g., `go`, `python`, `javascript`) You should see output containing: 1. The Go coding standards rule @@ -151,7 +152,7 @@ coding-context \ -p issue_key=BUG-123 \ -p description="Application crashes on startup" \ -s languages=go \ - /fix-bug | llm -m claude-3-5-sonnet-20241022 + fix-bug | llm -m claude-3-5-sonnet-20241022 ``` The AI agent will receive the assembled context and provide a response based on your coding standards and task requirements. @@ -167,7 +168,7 @@ coding-context \ -p issue_key=BUG-123 \ -p description="Application crashes on startup" \ -s languages=go \ - /fix-bug | llm -m claude-3-5-sonnet-20241022 + fix-bug | llm -m claude-3-5-sonnet-20241022 ``` This is useful for: From 5809ec4087f0ad12ed5db6b9f1ad9b25b6299960 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Dec 2025 23:47:16 +0000 Subject: [PATCH 5/5] Add comprehensive troubleshooting section to README Co-authored-by: alexec <1142830+alexec@users.noreply.github.com> --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index c8ed2d6..e1ac257 100644 --- a/README.md +++ b/README.md @@ -818,3 +818,35 @@ Perfect for: - **Tech talks** - Present at meetups or conferences - **Workshops** - Run hands-on training sessions - **Documentation** - Visual reference for features + +## Troubleshooting + +### Common Issues + +**Task not found** +- Verify the task file exists in `.agents/tasks/` with the correct filename +- Tasks are matched by filename (without `.md` extension), not by `task_name` in frontmatter +- Check that you're using the correct task name: `coding-context fix-bug` (not `/fix-bug`) + +**No rules included** +- Check that rule files exist in search paths (`.agents/rules/`, etc.) +- Verify selector syntax: use `-s languages=go` (not `-p languages=go`) +- Remember: `-s` filters rules, `-p` substitutes parameters +- Rules without frontmatter are always included (unless using resume mode) + +**Parameters not substituted** +- Ensure you're using `-p` flag: `coding-context -p issue=123 fix-bug` +- Check parameter names match exactly (case-sensitive): `${issue_key}` matches `-p issue_key=...` +- Verify the task file uses `${parameter}` syntax + +**Wrong rules included** +- Check frontmatter spelling and case sensitivity +- Use `languages:` (plural) in frontmatter and `-s languages=go` in selectors +- All selectors must match (AND logic): `-s languages=go -s stage=testing` + +**Bootstrap script not running** +- Make the script executable: `chmod +x .agents/rules/my-rule-bootstrap` +- Name it correctly: `{rule-filename}-bootstrap` (e.g., `jira-context-bootstrap` for `jira-context.md`) +- Check script output in stderr + +For 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).