anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 18:25:32 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

Improve AGENTS.md structure for task-specific instructions and reduced context crowding #738

New Issue
Closed
opened 2026-02-16 17:28:04 -05:00 by yindo · 4 comments
yindo commented 2026-02-16 17:28:04 -05:00
Owner
Copy Link
Copy Source

Originally created by @morgvanny on GitHub (Jul 15, 2025).

Originally assigned to: @thdxr on GitHub.

Problem

Currently, AGENTS.md files can become quite large with many different types of
instructions, which may lead to:

  1. Context crowding: Too many instructions in the context window may dilute
    the effectiveness of relevant rules
  2. Poor instruction adherence: Agents often don't follow specific
    instructions and need frequent reminders
  3. Task-irrelevant noise: Agents receive instructions for unrelated tasks,
    potentially causing confusion

Many rules/instructions are specific to certain types of tasks (e.g., testing
guidelines, API development standards, UI component patterns), but agents
working on unrelated tasks still receive all these instructions.

Current Solutions and Their Limitations

While opencode supports modular instruction files through opencode.json and
manual file references in AGENTS.md, these approaches don't fully solve the
context crowding issue:

opencode.json approach:

{
  "instructions": [
    "docs/typescript-guidelines.md",
    "test/testing-guidelines.md",
    "api/api-standards.md"
  ]
}

Limitation: All instruction files are loaded simultaneously into the
context, regardless of task relevance.

Manual file references in AGENTS.md:

For TypeScript code style: @docs/typescript-guidelines.md For testing:
@test/testing-guidelines.md

Limitations:

  • Relies on agent discretion to load files "on a need-to-know basis"
  • Inconsistent behavior - agents may not reliably determine which files are
    relevant
  • No systematic approach to map task types to instruction sets

Both approaches result in either everything being loaded at once (context
crowding) or inconsistent selective loading where agents may miss relevant
instructions or load irrelevant ones.

Why Current Approaches Fall Short in Practice

The manual file reference approach in AGENTS.md is conceptually sound - agents should load instruction files "on a need-to-know basis." However, in practice:

  • Inconsistent task recognition: Agents don't reliably identify when they're working on testing vs. API development vs. UI components
  • Missed relevant instructions: Agents may not load files that would actually help with their current task
  • No feedback loop: There's no mechanism to learn from cases where relevant instructions were missed
  • Cognitive load on agents: Agents must simultaneously understand the task AND remember which instruction files might be relevant

The issue isn't with the file reference mechanism itself, but with the lack of systematic task-to-instruction mapping that would make the selective loading more reliable and predictable.

Proposed Solution

Implement a task-aware instruction system where:

  1. AGENTS.md as a router: The main AGENTS.md acts as an index that defines
    task-to-instruction mappings
  2. Automatic task detection: opencode intelligently determines the type of
    task being performed
  3. Conditional instruction loading: Only load instruction files relevant to
    the current task type
  4. Systematic categorization: Clear mapping between task types and their
    associated instruction sets

Example Structure

AGENTS.md (main router with task mappings)
├── rules/
│   ├── general.md (always loaded)
│   ├── testing.md (loaded for test-related tasks)
│   ├── api-development.md (loaded for API work)
│   ├── ui-components.md (loaded for frontend tasks)
│   └── deployment.md (loaded for CI/CD tasks)

Example Task Mapping in AGENTS.md

## Task-Specific Instructions

- TASK_TYPE: testing -> load rules/testing.md, rules/general.md
- TASK_TYPE: api -> load rules/api-development.md, rules/general.md
- TASK_TYPE: ui -> load rules/ui-components.md, rules/accessibility.md,
  rules/general.md

Questions for Discussion

  1. Task detection: How could opencode best determine what type of task is
    being performed? (file patterns, user intent analysis, command context, etc.)
  2. Instruction categorization: What would be the best way to categorize/tag
    instructions for different task types?
  3. Fallback behavior: How should the system handle edge cases where task
    type is ambiguous?
  4. Backward compatibility: How can this be implemented while maintaining
    compatibility with existing AGENTS.md files?
  5. Performance: Would dynamic loading provide meaningful context window
    savings?

Impact

This improvement could:

  • Reduce context window usage by loading only relevant instructions
  • Improve instruction adherence by reducing noise and focusing on
    task-relevant rules
  • Make rule management more maintainable for complex projects with diverse
    workflows
  • Allow for better organization of project-specific guidelines
  • Enable more precise agent behavior tailored to specific development tasks

Would love to hear thoughts on whether this aligns with opencode's vision and if
there are other approaches worth considering for intelligent instruction
loading.

Originally created by @morgvanny on GitHub (Jul 15, 2025). Originally assigned to: @thdxr on GitHub. ## Problem Currently, AGENTS.md files can become quite large with many different types of instructions, which may lead to: 1. **Context crowding**: Too many instructions in the context window may dilute the effectiveness of relevant rules 2. **Poor instruction adherence**: Agents often don't follow specific instructions and need frequent reminders 3. **Task-irrelevant noise**: Agents receive instructions for unrelated tasks, potentially causing confusion Many rules/instructions are specific to certain types of tasks (e.g., testing guidelines, API development standards, UI component patterns), but agents working on unrelated tasks still receive all these instructions. ## Current Solutions and Their Limitations While opencode supports modular instruction files through `opencode.json` and manual file references in AGENTS.md, these approaches don't fully solve the context crowding issue: ### opencode.json approach: ```json { "instructions": [ "docs/typescript-guidelines.md", "test/testing-guidelines.md", "api/api-standards.md" ] } ``` **Limitation**: All instruction files are loaded simultaneously into the context, regardless of task relevance. ### Manual file references in AGENTS.md: ```markdown For TypeScript code style: @docs/typescript-guidelines.md For testing: @test/testing-guidelines.md ``` **Limitations**: - Relies on agent discretion to load files "on a need-to-know basis" - Inconsistent behavior - agents may not reliably determine which files are relevant - No systematic approach to map task types to instruction sets Both approaches result in either everything being loaded at once (context crowding) or inconsistent selective loading where agents may miss relevant instructions or load irrelevant ones. ## Why Current Approaches Fall Short in Practice The manual file reference approach in AGENTS.md is conceptually sound - agents should load instruction files "on a need-to-know basis." However, in practice: - **Inconsistent task recognition**: Agents don't reliably identify when they're working on testing vs. API development vs. UI components - **Missed relevant instructions**: Agents may not load files that would actually help with their current task - **No feedback loop**: There's no mechanism to learn from cases where relevant instructions were missed - **Cognitive load on agents**: Agents must simultaneously understand the task AND remember which instruction files might be relevant The issue isn't with the file reference mechanism itself, but with the lack of systematic task-to-instruction mapping that would make the selective loading more reliable and predictable. ## Proposed Solution Implement a **task-aware instruction system** where: 1. **AGENTS.md as a router**: The main AGENTS.md acts as an index that defines task-to-instruction mappings 2. **Automatic task detection**: opencode intelligently determines the type of task being performed 3. **Conditional instruction loading**: Only load instruction files relevant to the current task type 4. **Systematic categorization**: Clear mapping between task types and their associated instruction sets ### Example Structure ``` AGENTS.md (main router with task mappings) ├── rules/ │ ├── general.md (always loaded) │ ├── testing.md (loaded for test-related tasks) │ ├── api-development.md (loaded for API work) │ ├── ui-components.md (loaded for frontend tasks) │ └── deployment.md (loaded for CI/CD tasks) ``` ### Example Task Mapping in AGENTS.md ```markdown ## Task-Specific Instructions - TASK_TYPE: testing -> load rules/testing.md, rules/general.md - TASK_TYPE: api -> load rules/api-development.md, rules/general.md - TASK_TYPE: ui -> load rules/ui-components.md, rules/accessibility.md, rules/general.md ``` ## Questions for Discussion 1. **Task detection**: How could opencode best determine what type of task is being performed? (file patterns, user intent analysis, command context, etc.) 2. **Instruction categorization**: What would be the best way to categorize/tag instructions for different task types? 3. **Fallback behavior**: How should the system handle edge cases where task type is ambiguous? 4. **Backward compatibility**: How can this be implemented while maintaining compatibility with existing AGENTS.md files? 5. **Performance**: Would dynamic loading provide meaningful context window savings? ## Impact This improvement could: - **Reduce context window usage** by loading only relevant instructions - **Improve instruction adherence** by reducing noise and focusing on task-relevant rules - **Make rule management more maintainable** for complex projects with diverse workflows - **Allow for better organization** of project-specific guidelines - **Enable more precise agent behavior** tailored to specific development tasks Would love to hear thoughts on whether this aligns with opencode's vision and if there are other approaches worth considering for intelligent instruction loading.
yindo closed this issue 2026-02-16 17:28:04 -05:00
yindo commented 2026-02-16 17:28:04 -05:00
Author
Owner
Copy Link
Copy Source

@morgvanny commented on GitHub (Jul 15, 2025):

I had an idea that the new sub-agent feature could be used to go and determine the task type and ensure the right things get loaded, but I'm not sure if that makes the most sense or not

@morgvanny commented on GitHub (Jul 15, 2025): I had an idea that the new sub-agent feature could be used to go and determine the task type and ensure the right things get loaded, but I'm not sure if that makes the most sense or not
yindo commented 2026-02-16 17:28:04 -05:00
Author
Owner
Copy Link
Copy Source

@ironbelly commented on GitHub (Jul 20, 2025):

I had an idea that the new sub-agent feature could be used to go and determine the task type and ensure the right things get loaded, but I'm not sure if that makes the most sense or not

I believe SuperClaude is moving in that direction, not sure how much it's focused on context versus agent persona right now but going from the user specifying the persona and it happening automatically is the biggest change in V3

@ironbelly commented on GitHub (Jul 20, 2025): > I had an idea that the new sub-agent feature could be used to go and determine the task type and ensure the right things get loaded, but I'm not sure if that makes the most sense or not I believe SuperClaude is moving in that direction, not sure how much it's focused on context versus agent persona right now but going from the user specifying the persona and it happening automatically is the biggest change in V3
yindo commented 2026-02-16 17:28:05 -05:00
Author
Owner
Copy Link
Copy Source

@taxilian commented on GitHub (Aug 5, 2025):

Every time I've used agents I've wished at least once that I could say "make this agent primary until the task is done" and have it "hand off" to the other agent, then hand back at the end.

For example, I have a prompt for a project spec designer, one for an implementation planner, and one for a project lead; the first asks questions to figure out a detailed specification, the second takes the spec and splits it up into tasks and plans out phases, and the third actually implements those phases, doing parts in parallel using agents when possible.

In both claude code and opencode I have the same issue where to use this effectively I have to change out the AGENTS.md file with my instructions rather than relying on a subagent because I need it to be interactive, the subagent should be asking me questions to gather information

@taxilian commented on GitHub (Aug 5, 2025): Every time I've used agents I've wished at least once that I could say "make this agent primary until the task is done" and have it "hand off" to the other agent, then hand back at the end. For example, I have a prompt for a project spec designer, one for an implementation planner, and one for a project lead; the first asks questions to figure out a detailed specification, the second takes the spec and splits it up into tasks and plans out phases, and the third actually implements those phases, doing parts in parallel using agents when possible. In both claude code and opencode I have the same issue where to use this effectively I have to change out the AGENTS.md file with my instructions rather than relying on a subagent because I need it to be interactive, the subagent should be asking me questions to gather information
yindo commented 2026-02-16 17:28:05 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Dec 27, 2025):

[automated] Closing due to 90+ days of inactivity. Feel free to reopen if you still need this!

@rekram1-node commented on GitHub (Dec 27, 2025): [automated] Closing due to 90+ days of inactivity. Feel free to reopen if you still need this!
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#738
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?