Skip to content

Commit 34b28dc

Browse files
authored
feat(session-start): flexible project structure discovery (#31)
- Remove CLAUDE.md hardcoding (0% of projects had it) - Add explicit glob patterns for all discovery phases - Support .github/ content (AGENT_PROTOCOLS.md, CI docs) - Support .claude/ directories (agent configurations) - Add infrastructure project detection (config/, lib/, scripts/) - Provide 7-step discovery order with specific patterns Works across simple, complex, and infrastructure projects without hardcoded file assumptions. Tested against daphne, remory, and fuzu_infrastructure project structures.
1 parent 7ccd758 commit 34b28dc

1 file changed

Lines changed: 84 additions & 19 deletions

File tree

‎command/session-start.md‎

Lines changed: 84 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -60,34 +60,97 @@ remory search "contribution guidelines workflow conventions" --user-id "$PROJECT
6060
PHASE 2: DOCUMENTATION REVIEW (READ-ONLY TOOLS)
6161
═══════════════════════════════════════════════════════
6262

63-
**MANDATORY - Discover and read:**
64-
65-
1. **CLAUDE.md** - Project-specific instructions for AI agents
66-
2. **README.md** - Project overview and setup
67-
3. **Project workflow and contribution guidelines** - Figure out how this project operates
68-
- Common files: CONTRIBUTING.md, CODE_OF_CONDUCT.md, docs/contributing.md, .github/CONTRIBUTING.md
69-
- Use Read, Glob, or Grep as needed to discover what exists
63+
**MANDATORY - Discover and read (Priority Order):**
64+
65+
1. **README.md** - Project overview and setup
66+
- Pattern: `README.md` (root), `docs/README.md`
67+
- This is your primary source of project understanding
68+
69+
2. **Project-specific AI/agent instructions** - If they exist:
70+
- Patterns to discover: `CLAUDE.md`, `AGENTS.md`, `.claude/**/*.md`, `.github/AGENT*.md`
71+
- These define how AI agents should work with this project
72+
- Use Glob: Look for `CLAUDE.md` OR `AGENTS.md` OR patterns in `.claude/` OR `.github/`
73+
- Example: `glob: "CLAUDE.md"` or `glob: "AGENTS.md"` or `glob: ".claude/**/*.md"` or `glob: ".github/AGENT*.md"`
74+
- **Don't assume these exist** - skip if not found
75+
76+
3. **Project workflow and contribution guidelines:**
77+
- Patterns to discover: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `docs/contributing.md`, `.github/CONTRIBUTING.md`
78+
- Use Glob: `CONTRIBUTING.md` or `glob: "docs/contributing.md"` or `glob: ".github/CONTRIBUTING.md"`
7079
- These files define:
7180
- Commit message conventions
7281
- PR process and review requirements
7382
- Communication style and tone
7483
- Quality gates and testing requirements
7584
- Branch naming and workflow
7685
- **CRITICAL**: You must understand the workflow before doing any work
86+
- If found: Read in full. If not found: Proceed with assumptions from AGENTS.md
87+
88+
**OPTIONAL - Discover if they exist (Priority Order):**
89+
90+
4. **Testing conventions:**
91+
- Patterns: `TESTING.md`, `docs/testing.md`, `test/README.md`, `tests/README.md`
92+
- Use Glob: `TESTING.md` or `glob: "docs/testing.md"` or `glob: "test{s,}/README.md"`
93+
- Defines test requirements, coverage targets, testing approach
94+
95+
5. **Architecture and technical documentation:**
96+
- Patterns: `ARCHITECTURE.md`, `docs/architecture.md`, `docs/design.md`, `docs/technical-specification.md`
97+
- Use Glob: `glob: "docs/{architecture,design,technical-specification}.md"` or `ARCHITECTURE.md`
98+
- Explains system design, patterns, technical decisions
99+
100+
6. **Coding standards and conventions:**
101+
- Patterns: `STANDARDS.md`, `docs/conventions.md`, `style-guide.md`, `.editorconfig`
102+
- Use Glob: `glob: "docs/conventions.md"` or `STANDARDS.md`
103+
- Defines language-specific standards, naming, formatting
104+
105+
7. **GitHub-specific documentation:**
106+
- Patterns: `.github/*.md` (EXCLUDE workflow files in `.github/workflows/`)
107+
- Examples: `AGENT_PROTOCOLS.md`, `CI_IMPLEMENTATION_SUMMARY.md`, `CI_MONITORING_PROTOCOLS.md`
108+
- Use Glob: `glob: ".github/*.md"` (skip `.github/workflows/`)
109+
- Contains agent coordination patterns, CI/CD documentation
110+
111+
8. **Infrastructure patterns** (for DevOps/infrastructure projects):
112+
- Check for these directories: `config/`, `lib/`, `scripts/`
113+
- Use List: Check if directories exist with `list: "config/"`, `list: "lib/"`, `list: "scripts/"`
114+
- If 2+ directories exist: Note "Infrastructure project - review configs"
115+
- Pattern examples: `docs/blue-green-deployment.md`, `docs/s3-setup-guide.md`
116+
117+
**Discovery Approach (Use These Tools):**
118+
119+
1. **Start with mandatory files:**
120+
```
121+
Read: README.md
122+
Glob: "CLAUDE.md" (if missing, try "AGENTS.md")
123+
Glob: "CONTRIBUTING.md"
124+
```
77125

78-
**OPTIONAL - Discover if they exist:**
126+
2. **Check for agent-specific documentation:**
127+
```
128+
Glob: ".claude/**/*.md"
129+
Glob: ".github/AGENT*.md" or ".github/CI*.md" (exclude workflows/)
130+
```
79131

80-
4. **Testing conventions** - Examples: TESTING.md, docs/testing.md, test/README.md
81-
5. **Architecture documentation** - Examples: ARCHITECTURE.md, docs/architecture.md, docs/design.md
82-
6. **Coding standards** - Examples: STANDARDS.md, docs/conventions.md, style-guide.md
132+
3. **Discover documentation directories:**
133+
```
134+
List: docs/
135+
If exists, Glob: "docs/*.md"
136+
Prioritize: docs/contributing.md, docs/testing.md, docs/architecture.md
137+
```
138+
139+
4. **Check for infrastructure patterns:**
140+
```
141+
List: config/, lib/, scripts/
142+
If 2+ exist: Note "Infrastructure project - review deployment configs"
143+
```
83144

84-
**Approach:**
85-
- Be intelligent - use appropriate discovery tools (Read, Glob, Grep)
86-
- Try common filenames first, then search if needed
87-
- Read what exists, skip what doesn't
88-
- Projects structure documentation differently - adapt to what you find
145+
**File Discovery Order:**
146+
1. README.md (mandatory)
147+
2. AGENTS.md or CLAUDE.md (try both - if neither exists, continue)
148+
3. CONTRIBUTING.md (mandatory for workflow)
149+
4. docs/*.md (prioritize: testing, architecture, technical-specification)
150+
5. .github/*.md excluding workflows/ (if present)
151+
6. .claude/**/*.md (if present)
89152

90-
**Use Glob/Read/Grep tools only** - No bash commands for reading files
153+
**Use Glob/Read/List tools only** - No bash commands for reading files
91154

92155
═══════════════════════════════════════════════════════
93156
PHASE 3: GITHUB CONTEXT (DELEGATION REQUIRED)
@@ -171,7 +234,7 @@ PHASE 5: SUCCESS VERIFICATION & SUMMARY
171234
**SESSION READY CHECKLIST:**
172235
- [x] PROJECT_ID established
173236
- [x] Memory searched with specific queries
174-
- [x] Documentation reviewed (README, CLAUDE.md, conventions)
237+
- [x] Documentation reviewed (README, agent instructions if present, conventions)
175238
- [x] GitHub context gathered via @git-autonomous-agent
176239
- [x] All context stored in memory with --infer false
177240
- [x] TodoWrite tracking complete
@@ -229,7 +292,9 @@ CRITICAL RULES
229292
- Use GitHub API directly (https://api.github.com)
230293
- Use WebFetch for GitHub data
231294
- Use Perplexity for local project information
232-
- Use hardcoded filenames - use Glob patterns to discover files
295+
- **Use hardcoded filenames** - ALWAYS use Glob patterns to discover files (e.g., don't assume CLAUDE.md exists)
296+
- Assume documentation structure - adapt to what the project actually has
297+
- Skip files that don't exist - read what's there, not what you expect
233298
- Skip memory storage - it's MANDATORY for session continuity
234299

235300
═══════════════════════════════════════════════════════

0 commit comments

Comments
 (0)