docs: add agent design patterns documentation and improvement plan #39
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -111,6 +111,18 @@ Tasks with no open blockers - ready to work on. Use `/ready` to refresh this lis | |
| - Notes: Document how to analyze CI timing data for adaptive wait optimization. Include commands for extracting timing from GitHub Actions logs and updating shared-constants.sh. | ||
| - [ ] t050 Move SonarCloud hotspot patterns from AGENTS.md to code-review subagent #refactor #docs ~30m (ai:15m test:10m read:5m) logged:2025-01-11 | ||
| - Notes: AGENTS.md lines 85-89 contain SonarCloud hotspot patterns (S5332, S6506 exclusions). Move to tools/code-review/ subagent to reduce root AGENTS.md size. Low priority - patterns work fine where they are. | ||
| - [ ] t052 Agent Design Pattern Improvements #plan → [todo/PLANS.md#agent-design-pattern-improvements] ~1d (ai:6h test:4h read:2h) logged:2025-01-11 | ||
|
There was a problem hiding this comment. The anchor in 🤖 Was this useful? React with 👍 or 👎 |
||
| - Notes: Implement remaining improvements from Lance Martin's agent design patterns analysis. Includes: YAML frontmatter for subagents, automatic session reflection, cache-aware prompts, tool description indexing, memory consolidation. | ||
| - [ ] t053 Add YAML frontmatter to source subagents #architecture #agents ~2h (ai:1.5h test:30m) logged:2025-01-11 blocked-by:t052 | ||
| - Notes: Add description, triggers, tools fields to all .agent/**/*.md files. Update generate-opencode-agents.sh to parse frontmatter for better progressive disclosure. | ||
| - [ ] t054 Automatic session reflection to memory #workflow #memory ~4h (ai:2.5h test:1h read:30m) logged:2025-01-11 blocked-by:t052 | ||
| - Notes: Create session-distill-helper.sh to extract learnings. Integrate with /session-review. Auto-call /remember with distilled insights. | ||
| - [ ] t055 Document cache-aware prompt patterns #docs #optimization ~1h (ai:30m test:15m read:15m) logged:2025-01-11 blocked-by:t052 | ||
| - Notes: Add guidance to build-agent.md for stable-prefix patterns and avoiding instruction reordering for better prompt cache hits. | ||
| - [ ] t056 Tool description indexing for on-demand MCP discovery #tools #context ~3h (ai:2h test:45m read:15m) logged:2025-01-11 blocked-by:t052 | ||
| - Notes: Cursor-style MCP description sync to .agent-workspace/mcp-descriptions/. Add search tool for on-demand discovery instead of loading all tool definitions upfront. | ||
| - [ ] t057 Memory consolidation and pruning #memory #optimization ~2h (ai:1h test:45m read:15m) logged:2025-01-11 blocked-by:t052 | ||
| - Notes: Add memory-helper.sh consolidate command. Periodic reflection to merge similar memories and prune stale/superseded entries. | ||
|
|
||
| <!--TOON:backlog[38]{id,desc,owner,tags,est,est_ai,est_test,est_read,logged,status,blocked_by,blocks,parent}: | ||
| t010,Evaluate Merging build-agent and build-mcp into aidevops,,plan|architecture|agents,4h,2h,1h,1h,2025-12-21T14:00Z,pending,,, | ||
|
|
@@ -157,6 +169,12 @@ t047,TODO/PLANS sync with GitHub/GitLab/Gitea issues + cross-platform tools rese | |
| t048,Add worktree cleanup reminder to postflight workflow,,workflow|git,30m,15m,10m,5m,2025-01-10T00:00Z,pending,,, | ||
| t049,Add timing analysis commands to ralph-loop workflow,,workflow|automation,30m,15m,10m,5m,2025-01-10T00:00Z,pending,,, | ||
| t050,Move SonarCloud hotspot patterns from AGENTS.md to code-review subagent,,refactor|docs,30m,15m,10m,5m,2025-01-11T00:00Z,pending,,, | ||
| t052,Agent Design Pattern Improvements,,plan|architecture|agents|context|optimization,1d,6h,4h,2h,2025-01-11T00:00Z,pending,,, | ||
| t053,Add YAML frontmatter to source subagents,,architecture|agents,2h,1.5h,30m,,2025-01-11T00:00Z,pending,t052,, | ||
| t054,Automatic session reflection to memory,,workflow|memory,4h,2.5h,1h,30m,2025-01-11T00:00Z,pending,t052,, | ||
| t055,Document cache-aware prompt patterns,,docs|optimization,1h,30m,15m,15m,2025-01-11T00:00Z,pending,t052,, | ||
| t056,Tool description indexing for on-demand MCP discovery,,tools|context,3h,2h,45m,15m,2025-01-11T00:00Z,pending,t052,, | ||
| t057,Memory consolidation and pruning,,memory|optimization,2h,1h,45m,15m,2025-01-11T00:00Z,pending,t052,, | ||
| --> | ||
|
|
||
| <!--TOON:subtasks[0]{id,desc,est,status,blocked_by,parent}: | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -809,6 +809,91 @@ p005,Image SEO Enhancement with AI Vision,planning,0,4,,seo|images|ai|accessibil | |
| p006,Uncloud Integration for aidevops,planning,0,4,,deployment|docker|orchestration,1d,4h,4h,2h,2025-12-21T04:00Z, | ||
| p007,SEO Machine Integration for aidevops,planning,0,5,,seo|content|agents,2d,1d,0.5d,0.5d,2025-12-21T15:00Z, | ||
| p008,Enhance Plan+ and Build+ with OpenCode's Latest Features,planning,0,4,,opencode|agents|enhancement,3h,1.5h,1h,30m,2025-12-21T04:30Z, | ||
| p010,Agent Design Pattern Improvements,planning,0,5,,architecture|agents|context|optimization,1d,6h,4h,2h,2025-01-11T00:00Z, | ||
| --> | ||
|
|
||
| ### [2025-01-11] Agent Design Pattern Improvements | ||
|
|
||
| **Status:** Planning | ||
| **Estimate:** ~1d (ai:6h test:4h read:2h) | ||
| **Source:** [Lance Martin's "Effective Agent Design" (Jan 2025)](https://x.com/RLanceMartin/status/2009683038272401719) | ||
|
|
||
| <!--TOON:plan{id,title,status,phase,total_phases,owner,tags,est,est_ai,est_test,est_read,logged,started}: | ||
| p010,Agent Design Pattern Improvements,planning,0,5,,architecture|agents|context|optimization,1d,6h,4h,2h,2025-01-11T00:00Z, | ||
| --> | ||
|
|
||
| #### Purpose | ||
|
|
||
| Implement remaining agent design pattern improvements identified from Lance Martin's analysis of successful agents (Claude Code, Manus, Cursor). While aidevops already implements most patterns, these enhancements will further optimize context efficiency and enable automatic learning. | ||
|
|
||
| #### Context from Discussion | ||
|
|
||
| **What aidevops already does well:** | ||
| - Give agents a computer (filesystem + shell) | ||
| - Multi-layer action space (per-agent MCP filtering) | ||
| - Progressive disclosure (subagent tables, read-on-demand) | ||
| - Offload context to filesystem | ||
| - Ralph Loop (iterative execution) | ||
| - Memory system (/remember, /recall) | ||
|
|
||
| **Remaining opportunities:** | ||
|
|
||
| | Priority | Improvement | Estimate | Description | | ||
| |----------|-------------|----------|-------------| | ||
| | Medium | YAML frontmatter in source subagents | ~2h | Add frontmatter to all `.agent/**/*.md` for better progressive disclosure | | ||
| | Medium | Automatic session reflection | ~4h | Auto-distill sessions to memory on completion | | ||
| | Low | Cache-aware prompt structure | ~1h | Document stable-prefix patterns for better cache hits | | ||
| | Low | Tool description indexing | ~3h | Cursor-style MCP description sync for on-demand retrieval | | ||
| | Low | Memory consolidation | ~2h | Periodic reflection over memories to merge/prune | | ||
|
|
||
| #### Progress | ||
|
|
||
| - [ ] (2025-01-11) Phase 1: Add YAML frontmatter to source subagents ~2h | ||
| - Add `description`, `triggers`, `tools` to all `.agent/**/*.md` files | ||
| - Update `generate-opencode-agents.sh` to parse frontmatter | ||
| - [ ] (2025-01-11) Phase 2: Automatic session reflection ~4h | ||
| - Create `session-distill-helper.sh` to extract learnings | ||
| - Integrate with `/session-review` command | ||
| - Auto-call `/remember` with distilled insights | ||
| - [ ] (2025-01-11) Phase 3: Cache-aware prompt documentation ~1h | ||
| - Document stable-prefix patterns in `build-agent.md` | ||
| - Add guidance for avoiding instruction reordering | ||
| - [ ] (2025-01-11) Phase 4: Tool description indexing ~3h | ||
| - Create MCP description sync to `.agent-workspace/mcp-descriptions/` | ||
| - Add search tool for on-demand MCP discovery | ||
| - [ ] (2025-01-11) Phase 5: Memory consolidation ~2h | ||
| - Add `memory-helper.sh consolidate` command | ||
| - Periodic reflection to merge similar memories | ||
| - Prune stale or superseded entries | ||
|
|
||
| <!--TOON:milestones[5]{id,plan_id,desc,est,actual,scheduled,completed,status}: | ||
| m048,p010,Phase 1: Add YAML frontmatter to source subagents,2h,,2025-01-11T00:00Z,,pending | ||
| m049,p010,Phase 2: Automatic session reflection,4h,,2025-01-11T00:00Z,,pending | ||
| m050,p010,Phase 3: Cache-aware prompt documentation,1h,,2025-01-11T00:00Z,,pending | ||
| m051,p010,Phase 4: Tool description indexing,3h,,2025-01-11T00:00Z,,pending | ||
| m052,p010,Phase 5: Memory consolidation,2h,,2025-01-11T00:00Z,,pending | ||
| --> | ||
|
|
||
| #### Decision Log | ||
|
|
||
| - **Decision:** Document patterns before implementing improvements | ||
| **Rationale:** Establishes baseline, validates alignment, provides reference for future work | ||
| **Date:** 2025-01-11 | ||
|
|
||
| - **Decision:** Prioritize automatic session reflection over other improvements | ||
| **Rationale:** Highest impact for continual learning; other patterns already well-implemented | ||
| **Date:** 2025-01-11 | ||
|
|
||
| <!--TOON:decisions[2]{id,plan_id,decision,rationale,date,impact}: | ||
| d017,p010,Document patterns before implementing improvements,Establishes baseline and validates alignment,2025-01-11,None | ||
| d018,p010,Prioritize automatic session reflection,Highest impact for continual learning,2025-01-11,None | ||
| --> | ||
|
|
||
| #### Surprises & Discoveries | ||
|
|
||
| (To be populated during implementation) | ||
|
|
||
| <!--TOON:discoveries[0]{id,plan_id,observation,evidence,impact,date}: | ||
| --> | ||
|
|
||
| ## Completed Plans | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
generate-opencode-agents.shis referenced here (and below with line ranges), but in this repo it lives at.agent/scripts/generate-opencode-agents.sh(deployed to~/.aidevops/agents/scripts/), so the current reference may be hard to follow. Consider pointing to the full path and avoiding hardcoded line numbers that may drift as the script evolves.🤖 Was this useful? React with 👍 or 👎