Skip to content

Commit 75cac18

Browse files
hannesrudolphhannesrudolph
committed
fix: update init command description and content for clarity and accuracy
1 parent c97e3dd commit 75cac18

File tree

2 files changed

+212
-86
lines changed

2 files changed

+212
-86
lines changed

‎src/services/command/__tests__/built-in-commands.spec.ts‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,9 @@ describe("Built-in Commands", () => {
2929
expect(initCommand).toBeDefined()
3030
expect(initCommand!.content).toContain("AGENTS.md")
3131
expect(initCommand!.content).toContain(".roo/rules-")
32-
expect(initCommand!.description).toBe("Initialize a project with recommended rules and configuration")
32+
expect(initCommand!.description).toBe(
33+
"Analyze codebase and create concise AGENTS.md files for AI assistants",
34+
)
3335
})
3436
})
3537

@@ -42,7 +44,9 @@ describe("Built-in Commands", () => {
4244
expect(initCommand!.source).toBe("built-in")
4345
expect(initCommand!.filePath).toBe("<built-in:init>")
4446
expect(initCommand!.content).toContain("AGENTS.md")
45-
expect(initCommand!.description).toBe("Initialize a project with recommended rules and configuration")
47+
expect(initCommand!.description).toBe(
48+
"Analyze codebase and create concise AGENTS.md files for AI assistants",
49+
)
4650
})
4751

4852
it("should return undefined for non-existent command", async () => {
@@ -86,13 +90,15 @@ describe("Built-in Commands", () => {
8690
expect(content).toContain("Build/lint/test commands")
8791
expect(content).toContain("Code style guidelines")
8892
expect(content).toContain("mode-specific rule directories")
89-
expect(content).toContain("refer to the system prompt")
93+
expect(content).toContain("analysis_workflow")
9094

9195
// Should mention important concepts
9296
expect(content).toContain("AGENTS.md")
9397
expect(content).toContain(".roo/rules-")
94-
expect(content).toContain("four core modes")
95-
expect(content).toContain("mode-specific AGENTS.md files")
98+
expect(content).toContain("rules-code")
99+
expect(content).toContain("rules-debug")
100+
expect(content).toContain("rules-ask")
101+
expect(content).toContain("rules-architect")
96102
})
97103
})
98104
})

‎src/services/command/built-in-commands.ts‎

Lines changed: 201 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -10,94 +10,214 @@ interface BuiltInCommandDefinition {
1010
const BUILT_IN_COMMANDS: Record<string, BuiltInCommandDefinition> = {
1111
init: {
1212
name: "init",
13-
description: "Initialize a project with recommended rules and configuration",
14-
content: `Please analyze this codebase and create an AGENTS.md file containing:
13+
description: "Analyze codebase and create concise AGENTS.md files for AI assistants",
14+
content: `<task>
15+
Please analyze this codebase and create an AGENTS.md file containing:
1516
1. Build/lint/test commands - especially for running a single test
1617
2. Code style guidelines including imports, formatting, types, naming conventions, error handling, etc.
18+
</task>
1719
18-
Usage notes:
19-
- The file you create will be given to agentic coding agents (such as yourself) that operate in this repository. Make it about 20 lines long.
20-
- If there's already an AGENTS.md, improve it.
21-
- If there are Claude Code rules (in CLAUDE.md), Cursor rules (in .cursor/rules/ or .cursorrules), or Copilot rules (in .github/copilot-instructions.md), make sure to include them.
22-
- Be sure to prefix the file with the following text:
20+
<initialization>
21+
<purpose>
22+
Create (or update) a concise AGENTS.md file that enables immediate productivity for AI assistants.
23+
Focus on project-specific, non-obvious information. Prioritize brevity and scannability.
24+
25+
Usage notes:
26+
- The file you create will be given to agentic coding agents (such as yourself) that operate in this repository
27+
- Keep the main AGENTS.md concise - aim for about 20 lines, but use more if the project complexity requires it
28+
- If there's already an AGENTS.md, improve it
29+
- If there are Claude Code rules (in CLAUDE.md), Cursor rules (in .cursor/rules/ or .cursorrules), or Copilot rules (in .github/copilot-instructions.md), make sure to include them
30+
- Be sure to prefix the file with: "# AGENTS.md\\n\\nThis file provides guidance to agents when working with code in this repository."
31+
</purpose>
32+
33+
<todo_list_creation>
34+
If the update_todo_list tool is available, create a todo list with these focused analysis steps:
35+
36+
1. Quick scan for existing docs
37+
- AI assistant rules (.cursorrules, CLAUDE.md, AGENTS.md, .roorules)
38+
- README and key documentation
39+
40+
2. Identify stack
41+
- Language, framework, build tools
42+
- Package manager and dependencies
43+
44+
3. Extract commands
45+
- Build, test, lint, run
46+
- Critical directory-specific commands
47+
48+
4. Map core architecture
49+
- Main components and flow
50+
- Key entry points
51+
52+
5. Document critical patterns
53+
- Project-specific utilities
54+
- Non-standard approaches
55+
56+
6. Extract code style
57+
- From config files only
58+
- Key conventions
59+
60+
7. Testing specifics
61+
- Framework and run commands
62+
- Directory requirements
63+
64+
8. Compile concise AGENTS.md
65+
- Essential sections only
66+
- Brief, scannable format
67+
- Project-specific focus
68+
69+
9. Create mode-specific rule directories
70+
- Create directory structures for the four core modes: .roo/rules-code/, .roo/rules-ask/, .roo/rules-architect/, .roo/rules-debug/
71+
- Create mode-specific AGENTS.md files with rules specific to that mode's purpose and capabilities
72+
- These rules should provide additive context and not just repeat the mode definitions
73+
- Only include rules that you have high confidence are accurate, valuable, and non-obvious
74+
75+
Note: If update_todo_list is not available, proceed with the analysis workflow directly without creating a todo list.
76+
</todo_list_creation>
77+
</initialization>
2378
24-
# AGENTS.md
79+
<analysis_workflow>
80+
Follow the comprehensive analysis workflow to:
81+
82+
1. **Discovery Phase**: Find existing documentation and AI assistant rules
83+
2. **Project Identification**: Identify language, stack, and build system
84+
3. **Command Extraction**: Extract and verify essential commands
85+
4. **Architecture Mapping**: Create visual flow diagrams of core processes
86+
5. **Component Analysis**: Document key components and their interactions
87+
6. **Pattern Analysis**: Identify project-specific patterns and conventions
88+
7. **Code Style Extraction**: Extract formatting and naming conventions
89+
8. **Security & Performance**: Document critical patterns if relevant
90+
9. **Testing Discovery**: Understand testing setup and practices
91+
10. **Example Extraction**: Find real examples from the codebase
92+
</analysis_workflow>
2593
26-
This file provides guidance to agents when working with code in this repository.
94+
<output_structure>
95+
<main_file>
96+
Create AGENTS.md with:
97+
- Header: "# AGENTS.md\\n\\nThis file provides guidance to agents when working with code in this repository."
98+
- Project overview (brief description, core functionality, key technologies)
99+
- Build/lint/test commands - especially for running a single test
100+
- Code style guidelines including imports, formatting, types, naming conventions, error handling, etc.
101+
- Architecture overview (visual flow diagrams using ASCII/markdown)
102+
- Development guides (step-by-step for common tasks)
103+
- Project-specific patterns (custom utilities, non-standard approaches)
104+
- Testing guidelines (how to write and run tests)
105+
- Critical rules (must-follow requirements)
106+
107+
Keep it concise (aim for ~20 lines, but expand as needed for complex projects) and focused on essential, project-specific information.
108+
Include existing AI assistant rules from CLAUDE.md, Cursor rules (.cursor/rules/ or .cursorrules), or Copilot rules (.github/copilot-instructions.md).
109+
</main_file>
110+
111+
<mode_specific_files>
112+
Additionally, create mode-specific rule directories and AGENTS.md files.
113+
For the complete list of available modes with detailed descriptions, refer to the system prompt.
114+
The system prompt contains comprehensive information about each mode's purpose, when to use it, and its specific capabilities.
115+
116+
Example structure:
117+
\`\`\`
118+
AGENTS.md # General project guidance
119+
.roo/
120+
├── rules-code/
121+
│ └── AGENTS.md # Code mode specific instructions
122+
├── rules-debug/
123+
│ └── AGENTS.md # Debug mode specific instructions
124+
├── rules-ask/
125+
│ └── AGENTS.md # Ask mode specific instructions
126+
└── rules-architect/
127+
└── AGENTS.md # Architect mode specific instructions
128+
\`\`\`
129+
130+
Create mode-specific AGENTS.md files in:
131+
132+
.roo/rules-code/AGENTS.md - Project-specific coding rules:
133+
- Custom utilities that must be used
134+
- API patterns and retry mechanisms
135+
- UI component guidelines
136+
- Database query patterns
137+
- Provider implementation requirements
138+
- Test coverage requirements
139+
140+
Example of actual rules to document:
141+
\`\`\`
142+
# Project Coding Rules
143+
- All API calls must use the retry mechanism in src/api/providers/utils/
144+
- UI components should use Tailwind CSS classes, not inline styles
145+
- New providers must implement the Provider interface in packages/types/src/
146+
- Database queries must use the query builder in packages/evals/src/db/queries/
147+
- Always use safeWriteJson() from src/utils/ instead of JSON.stringify for file writes
148+
- Test coverage required for all new features in src/ and webview-ui/
149+
\`\`\`
150+
151+
.roo/rules-debug/AGENTS.md - Project-specific debugging approaches:
152+
- Where to find logs and debug output
153+
- Common debugging tools and commands
154+
- Test patterns for reproducing issues
155+
- Database and migration debugging
156+
- IPC and communication debugging
157+
- Build-specific debugging tips
158+
159+
Example of actual rules to document:
160+
\`\`\`
161+
# Project Debug Rules
162+
- Check VSCode extension logs in the Debug Console
163+
- For webview issues, inspect the webview dev tools via Command Palette
164+
- Provider issues: check src/api/providers/__tests__/ for similar test patterns
165+
- Database issues: run migrations in packages/evals/src/db/migrations/
166+
- IPC communication issues: review packages/ipc/src/ message patterns
167+
- Always reproduce in both development and production extension builds
168+
\`\`\`
169+
170+
.roo/rules-ask/AGENTS.md - Project documentation context:
171+
- Repository structure explanation
172+
- Where to find examples and patterns
173+
- Key documentation locations
174+
- Build and test command references
175+
- Localization and i18n patterns
176+
- Architecture-specific explanations
177+
178+
Example of actual rules to document:
179+
\`\`\`
180+
# Project Documentation Rules
181+
- Reference the monorepo structure: src/ (VSCode extension), apps/ (web apps), packages/ (shared)
182+
- Explain provider patterns by referencing existing ones in src/api/providers/
183+
- For UI questions, reference webview-ui/ React components and their patterns
184+
- Point to package.json scripts for build/test commands
185+
- Reference locales/ for i18n patterns when discussing translations
186+
- Always mention the VSCode webview architecture when discussing UI
187+
\`\`\`
188+
189+
.roo/rules-architect/AGENTS.md - Project architectural considerations:
190+
- Extension and plugin architecture
191+
- State management patterns
192+
- Database schema requirements
193+
- Package organization rules
194+
- API compatibility requirements
195+
- Performance and scaling considerations
196+
197+
Example of actual rules to document:
198+
\`\`\`
199+
# Project Architecture Rules
200+
- New features must work within VSCode extension + webview architecture
201+
- Provider implementations must be stateless and cacheable
202+
- UI state management uses React hooks, not external state libraries
203+
- Database schema changes require migrations in packages/evals/src/db/migrations/
204+
- New packages must follow the existing monorepo structure in packages/
205+
- API changes must maintain backward compatibility with existing provider contracts
206+
\`\`\`
207+
</mode_specific_files>
208+
</output_structure>
27209
28-
Additionally, please:
29-
1. **Create mode-specific rule directories** - Create directory structures for the four core modes: \`.roo/rules-code/\`, \`.roo/rules-ask/\`, \`.roo/rules-architect/\`, and \`.roo/rules-debug/\`
30-
2. **Create mode-specific AGENTS.md files** - Within each of these four mode directories, research and then create an AGENTS.md file with rules specific to that mode's purpose and capabilities. These rules should provide additive context and not just repeat the mode definitions. Only include rules that you have high confidence are accurate, valuable, and non-obvious.
210+
<quality_criteria>
211+
- Include visual flow diagrams (ASCII/markdown) for architecture
212+
- Provide actionable, step-by-step guides
213+
- Focus on non-obvious, project-specific information
214+
- Include real code examples from the project
215+
- Be concise and scannable
216+
- Adapt to the specific project needs
217+
- Document only what's essential for productivity
218+
</quality_criteria>
31219
32-
**For the complete list of available modes with detailed descriptions, refer to the system prompt.** The system prompt contains comprehensive information about each mode's purpose, when to use it, and its specific capabilities.
33-
34-
Example structure with specific instructions:
35-
36-
\\\`\\\`\\\`
37-
AGENTS.md # General project guidance
38-
.roo/
39-
├── rules-code/
40-
│ └── AGENTS.md # Code mode specific instructions
41-
├── rules-debug/
42-
│ └── AGENTS.md # Debug mode specific instructions
43-
├── rules-ask/
44-
│ └── AGENTS.md # Ask mode specific instructions
45-
└── rules-architect/
46-
└── AGENTS.md # Architect mode specific instructions
47-
\\\`\\\`\\\`
48-
49-
**Example project-specific instructions:**
50-
51-
**\`.roo/rules-code/AGENTS.md\`** - Project-specific coding rules:
52-
\\\`\\\`\\\`
53-
# Project Coding Rules
54-
55-
- All API calls must use the retry mechanism in src/api/providers/utils/
56-
- UI components should use Tailwind CSS classes, not inline styles
57-
- New providers must implement the Provider interface in packages/types/src/
58-
- Database queries must use the query builder in packages/evals/src/db/queries/
59-
- Always use safeWriteJson() from src/utils/ instead of JSON.stringify for file writes
60-
- Test coverage required for all new features in src/ and webview-ui/
61-
\\\`\\\`\\\`
62-
63-
**\`.roo/rules-debug/AGENTS.md\`** - Project-specific debugging approaches:
64-
\\\`\\\`\\\`
65-
# Project Debug Rules
66-
67-
- Check VSCode extension logs in the Debug Console
68-
- For webview issues, inspect the webview dev tools via Command Palette
69-
- Provider issues: check src/api/providers/__tests__/ for similar test patterns
70-
- Database issues: run migrations in packages/evals/src/db/migrations/
71-
- IPC communication issues: review packages/ipc/src/ message patterns
72-
- Always reproduce in both development and production extension builds
73-
\\\`\\\`\\\`
74-
75-
**\`.roo/rules-ask/AGENTS.md\`** - Project-specific explanation context:
76-
\\\`\\\`\\\`
77-
# Project Documentation Rules
78-
79-
- Reference the monorepo structure: src/ (VSCode extension), apps/ (web apps), packages/ (shared)
80-
- Explain provider patterns by referencing existing ones in src/api/providers/
81-
- For UI questions, reference webview-ui/ React components and their patterns
82-
- Point to package.json scripts for build/test commands
83-
- Reference locales/ for i18n patterns when discussing translations
84-
- Always mention the VSCode webview architecture when discussing UI
85-
\\\`\\\`\\\`
86-
87-
**\`.roo/rules-architect/AGENTS.md\`** - Project-specific architectural considerations:
88-
\\\`\\\`\\\`
89-
# Project Architecture Rules
90-
91-
- New features must work within VSCode extension + webview architecture
92-
- Provider implementations must be stateless and cacheable
93-
- UI state management uses React hooks, not external state libraries
94-
- Database schema changes require migrations in packages/evals/src/db/migrations/
95-
- New packages must follow the existing monorepo structure in packages/
96-
- API changes must maintain backward compatibility with existing provider contracts
97-
\\\`\\\`\\\`
98-
99-
This structure provides both general project guidance and specialized instructions for the four core modes' specific domains and workflows.
100-
`,
220+
Remember: The goal is to create documentation that enables AI assistants to be immediately productive in this codebase, focusing on project-specific knowledge that isn't obvious from the code structure alone.`,
101221
},
102222
}
103223

0 commit comments

Comments
 (0)