Skip to content

Fix documentation discrepancies with actual code behavior #166

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexec merged 8 commits into from
Dec 22, 2025
Merged

Fix documentation discrepancies with actual code behavior #166

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
04593db
Initial plan
Copilot Dec 17, 2025
695146f
Add user-prompt argument to documentation and fix flag descriptions
Copilot Dec 17, 2025
2fe0ca6
Fix search paths documentation to match code implementation
Copilot Dec 17, 2025
5521426
Fix task invocation examples - remove incorrect slash prefix
Copilot Dec 17, 2025
d0523cb
Correct agent flag documentation to match actual behavior
Copilot Dec 17, 2025
fe96dff
Update main.go
alexec Dec 17, 2025
79010f6
Update README.md
alexec Dec 17, 2025
315bb6b
Remove incorrect agent filtering claims from documentation
Copilot Dec 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 45 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,17 @@ sudo chmod +x /usr/local/bin/coding-context

```
Usage:
coding-context [options] <task-name>
coding-context [options] <task-name> [user-prompt]

Arguments:
<task-name>
The name of a task file to look up in task search paths (.agents/tasks).
Task files are matched by filename (without .md extension).

[user-prompt] (optional)
Optional text to append to the task. It can contain slash commands
(e.g., '/command-name') which will be expanded, and parameter
substitution (${param}).

Options:
-C string
Expand All @@ -96,7 +106,7 @@ Options:
Include rules with matching frontmatter. Can be specified multiple times as key=value.
Note: Only matches top-level YAML fields in frontmatter.
-a string
Default agent to use if task doesn't specify one. Excludes that agent's own rule paths (since the agent reads those itself). Supported agents: cursor, opencode, copilot, claude, gemini, augment, windsurf, codex.
Target agent to use (excludes rules from that agent's own paths). Supported agents: cursor, opencode, copilot, claude, gemini, augment, windsurf, codex.
-w Write rules to agent's config file and output only task to stdout. Requires agent (via task or -a flag).
```

Expand Down Expand Up @@ -179,22 +189,22 @@ Each of these would have a corresponding `.md` file (e.g., `triage-bug.md`, `fix

The tool assembles the context in the following order:

1. **Rule Files**: It searches a list of predefined locations for rule files (`.md` or `.mdc`). These locations include the current directory, ancestor directories, user's home directory, and system-wide directories.
1. **Rule Files**: It searches for rule files (`.md` or `.mdc`) in directories specified via `-d` flags and automatically-added working directory and home directory.
2. **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.
3. **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.
4. **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.
5. **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.
6. **Parameter Expansion**: It substitutes variables in the task prompt using the `-p` flags.
7. **Output**: It prints the content of all included rule files, followed by the expanded task prompt, to standard output.
8. **Token Count**: A running total of estimated tokens is printed to standard error.
6. **User Prompt Appending**: If a user-prompt argument is provided, it is appended to the task content after a delimiter (`---`).
7. **Parameter Expansion**: It substitutes variables in the task prompt and user-prompt using the `-p` flags.
8. **Output**: It prints the content of all included rule files, followed by the expanded task prompt, to standard output.
9. **Token Count**: A running total of estimated tokens is printed to standard error.

### 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)
- `~/.agents/tasks/*.md`

**Commands** (reusable content blocks referenced via slash commands like `/command-name` inside task content):
- `./.agents/commands/*.md`
Expand All @@ -204,9 +214,9 @@ The tool looks for task and rule files in the following locations, in order of p
**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`, `.opencode/rules`
- `.github/copilot-instructions.md`, `.github/agents`, `.gemini/styleguide.md`
- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.codex/AGENTS.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.

### Remote File System Support
Expand Down Expand Up @@ -300,10 +310,10 @@ Deploy the application to production with all safety checks.
You can then select the appropriate task using:
```bash
# Deploy to staging
coding-context -s environment=staging /deploy
coding-context -s environment=staging deploy

# Deploy to production
coding-context -s environment=production /deploy
coding-context -s environment=production deploy
```

#### Task Frontmatter Selectors
Expand All @@ -328,11 +338,6 @@ When you run this task, it automatically applies the selectors:
coding-context implement-feature
```

This is equivalent to:
```bash
coding-context -s languages=go -s stage=implementation /implement-feature
```

**Selectors support OR logic for the same key using arrays:**
```markdown
---
Expand Down Expand Up @@ -394,13 +399,12 @@ This is particularly useful in agentic workflows where an AI agent has already b
- Skipping all rules output

**Example usage:**

```bash
# Initial task invocation (includes all rules, uses task with resume: false)
coding-context -s resume=false /fix-bug | ai-agent
coding-context -s resume=false fix-bug | ai-agent

# Resume the task (skips rules, uses task with resume: true)
coding-context -r /fix-bug | ai-agent
coding-context -r fix-bug | ai-agent
```

**Example task files for resume mode:**
Expand Down Expand Up @@ -449,7 +453,7 @@ languages:
To include this rule only when working on Go code, you would use `-s languages=go`:

```bash
coding-context -s languages=go /fix-bug
coding-context -s languages=go fix-bug
```

This will include all rules with `languages: [ go ]` in their frontmatter, excluding rules for other languages.
Expand All @@ -468,10 +472,10 @@ Then select only the relevant rules:

```bash
# Work on Python code with Python-specific rules
coding-context -s languages=python /fix-bug
coding-context -s languages=python fix-bug

# Work on JavaScript code with JavaScript-specific rules
coding-context -s languages=javascript /enhance-feature
coding-context -s languages=javascript enhance-feature
```

**Language Values**
Expand Down Expand Up @@ -503,32 +507,33 @@ If you need to filter on nested data, flatten your frontmatter structure to use

### Targeting a Specific Agent

When working with a specific AI coding agent, the agent itself will read its own configuration files. The `-a` flag lets you specify which agent you're using, automatically excluding that agent's specific rule paths while including rules from other agents and generic rules.
The `-a` flag specifies which AI coding agent you're using. This information is currently used in one way:

1. **Write Rules Mode**: With the `-w` flag, determines where to write rules (e.g., `~/.github/agents/AGENTS.md` for `copilot`)

> Note: Agent-based rule filtering is not implemented. All rules are currently included regardless of the `-a` value.
**Supported agents:**
- `cursor` - Excludes `.cursor/rules`, `.cursorrules`; includes other agents and generic rules
- `opencode` - Excludes `.opencode/agent`, `.opencode/command`; includes other agents and generic rules
- `copilot` - Excludes `.github/copilot-instructions.md`, `.github/agents`; includes other agents and generic rules
- `claude` - Excludes `.claude/`, `CLAUDE.md`, `CLAUDE.local.md`; includes other agents and generic rules
- `gemini` - Excludes `.gemini/`, `GEMINI.md`; includes other agents and generic rules
- `augment` - Excludes `.augment/`; includes other agents and generic rules
- `windsurf` - Excludes `.windsurf/`, `.windsurfrules`; includes other agents and generic rules
- `codex` - Excludes `.codex/`, `AGENTS.md`; includes other agents and generic rules
- `cursor` - Cursor IDE
- `opencode` - OpenCode.ai
- `copilot` - GitHub Copilot
- `claude` - Anthropic Claude
- `gemini` - Google Gemini
- `augment` - Augment
- `windsurf` - Windsurf
- `codex` - Codex

**Example: Using Cursor:**
**Example: Agent-specific rules:**

```bash
# When using Cursor, exclude .cursor/ and .cursorrules (Cursor reads those itself)
# But include rules from other agents and generic rules
coding-context -a cursor /fix-bug
# Specify the agent
coding-context -a cursor fix-bug
```
Copy link

Copilot AI Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example documentation incorrectly describes agent-based rule filtering. The example claims to show "Agent-specific rules" where specifying an agent filters rules, but the code does not implement this filtering. The agent flag only sets the agent value for potential use by the caller (e.g., for determining write paths with -w), but does not filter rules based on agent.

Copilot uses AI. Check for mistakes.
Copy link
Contributor

@alexec alexec Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

Copy link
Contributor Author

Copilot AI Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in commit 315bb6b. Removed the "Agent-specific rules" section that incorrectly described filtering. Replaced with accurate documentation about using agent with -w flag for write mode.


**How it works:**
- The `-a` flag sets the target agent
- The target agent's own paths are excluded (e.g., `.cursor/` for cursor)
- Rules from other agents are included (e.g., `.opencode/`, `.github/copilot-instructions.md`)
- Generic rules (from `.agents/rules`) are always included
- The agent name is automatically added as a selector, so generic rules can filter themselves with `agent: cursor` in frontmatter
- The agent name is automatically added as a selector for rule filtering
- Rules can use `agent: cursor` in frontmatter to match only when that agent is specified
- Generic rules (without an agent field) are always included
Copy link

Copilot AI Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These lines incorrectly describe agent-based rule filtering. Lines 534-536 claim the agent name is added as a selector and that rules can filter based on agent, but this is not implemented in the code. The agent value is stored but never used for filtering rules. The test file context_test.go at line 533 has a comment confirming "Agent filtering is not implemented, so all rules are included".

Copilot uses AI. Check for mistakes.
Copy link
Contributor

@alexec alexec Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

Copy link
Contributor Author

Copilot AI Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in commit 315bb6b. Removed lines 534-536 that incorrectly claimed agent is added as selector. Section now clearly states agent is only used for -w write path, with note that rule filtering is not implemented.


**Example generic rule with agent filtering:**

Expand All @@ -553,14 +558,6 @@ agent: cursor

This is useful for tasks designed for specific agents, ensuring the correct agent context is used regardless of command-line flags.

**Use cases:**
- **Avoid duplication**: The agent reads its own config, so exclude it from the context
- **Cross-agent rules**: Include rules from other agents that might be relevant
- **Generic rules**: Always include generic rules, with optional agent-specific filtering
- **Task-specific agents**: Tasks can enforce a specific agent context

The exclusion happens before rule processing, so excluded paths are never loaded or counted toward token estimates.

### Bootstrap Scripts

A 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.
Expand Down
4 changes: 2 additions & 2 deletions docs/how-to/create-tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Please review the code changes with focus on:
- Security implications
```

Save as `.agents/tasks/code-review.md` (or `.agents/commands/code-review.md`).
Save as `.agents/tasks/code-review.md`.

Use with:
```bash
Expand Down Expand Up @@ -51,7 +51,7 @@ coding-context \
-p feature_name="User Authentication" \
-p requirements="OAuth2 support, secure password storage" \
-p success_criteria="All tests pass, security audit clean" \
/implement-feature
implement-feature
```

## Multiple Tasks with Selectors
Expand Down
2 changes: 1 addition & 1 deletion docs/how-to/github-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,7 +209,7 @@ Use the `-C` flag to run from a different directory:
```yaml
- name: Assemble Context
run: |
coding-context -C ./backend -s languages=go /fix-bug > context.txt
coding-context -C ./backend -s languages=go fix-bug > context.txt
```

## Best Practices
Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ sudo curl -fsL -o /usr/local/bin/coding-context \
sudo chmod +x /usr/local/bin/coding-context

# Use with an AI agent
coding-context -p issue_key=BUG-123 -s languages=go /fix-bug | llm -m claude-3-5-sonnet-20241022
coding-context -p issue_key=BUG-123 -s languages=go fix-bug | llm -m claude-3-5-sonnet-20241022
```

## Documentation Structure
Expand Down
Loading