Skip to content

Commit 94d3e8f

Browse files
committed
Merge main into refactor/agent-naming-consistency
Resolved conflicts by keeping PR's fixes (removing buggy deny-all rules): - Removed bash "*": "deny" from coder-agent.md (was blocking bash usage) - Removed task "*": "deny" from all three files (was blocking task delegations) - Preserved TestEngineer allow rule in coder-agent.md - Kept all PR's agent naming standardization changes The "*": "deny" rules were bugs that prevented proper permission inheritance.
2 parents 8b442b6 + ca2e35c commit 94d3e8f

File tree

146 files changed

+33248
-7329
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

146 files changed

+33248
-7329
lines changed

.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,3 +207,5 @@ tasks/
207207

208208
# Claude Code integration generated files
209209
integrations/claude-code/converter/generated/
210+
.cursorrules
211+
bun.lock
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Guide: Designing Navigation Files
2+
3+
**Purpose**: How to create token-efficient, scannable navigation files
4+
5+
---
6+
7+
## Prerequisites
8+
9+
- Understand MVI principle (`context-system/standards/mvi.md`)
10+
- Know your category's organizational pattern
11+
- Have content files already created
12+
13+
**Estimated time**: 15-20 min per navigation file
14+
15+
---
16+
17+
## Core Principles
18+
19+
### 1. Token Efficiency
20+
**Goal**: 200-300 tokens per navigation file
21+
22+
**How**:
23+
- Use ASCII trees (not verbose descriptions)
24+
- Use tables (not paragraphs)
25+
- Be concise (not comprehensive)
26+
27+
### 2. Scannable Structure
28+
**Goal**: AI can find what it needs in <5 seconds
29+
30+
**Format**:
31+
1. **Structure** (ASCII tree) - See what exists
32+
2. **Quick Routes** (table) - Jump to common tasks
33+
3. **By Concern/Type** (sections) - Browse by category
34+
35+
### 3. Self-Contained
36+
**Include**: ✅ Paths | ✅ Brief descriptions (3-5 words) | ✅ When to use
37+
**Exclude**: ❌ File contents | ❌ Detailed explanations | ❌ Duplicates
38+
39+
---
40+
41+
## Steps
42+
43+
### 1. Determine Navigation Type
44+
45+
| Type | Path | Purpose |
46+
|------|------|---------|
47+
| Category-level | `{category}/navigation.md` | Overview of category |
48+
| Subcategory-level | `{category}/{sub}/navigation.md` | Files in subcategory |
49+
| Specialized | `{category}/{domain}-navigation.md` | Cross-cutting (e.g., ui-navigation.md) |
50+
51+
### 2. Create Structure Section
52+
53+
```markdown
54+
## Structure
55+
56+
```
57+
openagents-repo/
58+
├── navigation.md
59+
├── quick-start.md
60+
├── concepts/
61+
│ └── subagent-testing-modes.md
62+
├── guides/
63+
│ ├── adding-agent.md
64+
│ └── testing-agent.md
65+
└── lookup/
66+
└── commands.md
67+
```
68+
```
69+
70+
**Token count**: ~50-100 tokens
71+
72+
### 3. Create Quick Routes Table
73+
74+
```markdown
75+
## Quick Routes
76+
77+
| Task | Path |
78+
|------|------|
79+
| **Add agent** | `guides/adding-agent.md` |
80+
| **Test agent** | `guides/testing-agent.md` |
81+
| **Find files** | `lookup/file-locations.md` |
82+
```
83+
84+
**Guidelines**: Use **bold** for tasks | Relative paths | 5-10 common tasks
85+
86+
### 4. Create By Concern/Type Sections
87+
88+
```markdown
89+
## By Type
90+
91+
**Concepts** → Core ideas and principles
92+
**Guides** → Step-by-step workflows
93+
**Lookup** → Quick reference tables
94+
**Errors** → Troubleshooting
95+
```
96+
97+
### 5. Add Related Context (Optional)
98+
99+
```markdown
100+
## Related Context
101+
102+
- **Core Standards**`../core/standards/navigation.md`
103+
```
104+
105+
### 6. Validate Token Count
106+
107+
**Target**: 200-300 tokens
108+
109+
```bash
110+
wc -w navigation.md # Multiply by 1.3 for token estimate
111+
```
112+
113+
---
114+
115+
## Verification Checklist
116+
117+
- [ ] Token count 200-300?
118+
- [ ] ASCII tree included?
119+
- [ ] Quick routes table?
120+
- [ ] By concern/type section?
121+
- [ ] Relative paths?
122+
- [ ] Descriptions 3-5 words?
123+
- [ ] No duplicate information?
124+
125+
---
126+
127+
## Related
128+
129+
- `navigation-templates.md` - Ready-to-use templates
130+
- `../standards/mvi.md` - MVI principle
131+
- `../examples/navigation-examples.md` - More examples

0 commit comments

Comments
 (0)