feat: add codebase-doc mode for project documentation generation

src/shared/__tests__/modes.spec.ts

@@ -498,6 +498,65 @@ describe("FileRestrictionError", () => {
 	})
 })
 
+describe("codebase-doc mode", () => {
+	it("is configured correctly", () => {
+		const codebaseDocMode = modes.find((mode) => mode.slug === "codebase-doc")
+		expect(codebaseDocMode).toBeDefined()
+		expect(codebaseDocMode).toMatchObject({
+			slug: "codebase-doc",
+			name: "🗂️ Codebase Documentation Generator",
+			roleDefinition:
+				"You are a codebase analyst and documentation generator. Your job is to analyze the project structure, environment, and dependencies, and generate a PROJECT_DOC.md file with actionable context.",
+			whenToUse:
+				"Use this mode to create or update project documentation and provide environment-specific guidance.",
+			description: "Generate comprehensive project documentation",
+			groups: ["read", "edit", "browser"],
+		})
+		expect(codebaseDocMode?.customInstructions).toContain("PROJECT_DOC.md Template")
+		expect(codebaseDocMode?.customInstructions).toContain("Use existing tools")
+		expect(codebaseDocMode?.customInstructions).toContain("list_files")
+		expect(codebaseDocMode?.customInstructions).toContain("read_file")
+		expect(codebaseDocMode?.customInstructions).toContain("write_to_file")
+	})
+
+	it("allows read, edit, and browser tools", () => {
+		expect(isToolAllowedForMode("read_file", "codebase-doc", [])).toBe(true)
+		expect(isToolAllowedForMode("list_files", "codebase-doc", [])).toBe(true)
+		expect(isToolAllowedForMode("search_files", "codebase-doc", [])).toBe(true)
+		expect(isToolAllowedForMode("write_to_file", "codebase-doc", [])).toBe(true)
+		expect(isToolAllowedForMode("browser_action", "codebase-doc", [])).toBe(true)
+	})
+
+	it("does not allow command or mcp tools", () => {
+		expect(isToolAllowedForMode("execute_command", "codebase-doc", [])).toBe(false)
+		expect(isToolAllowedForMode("use_mcp_tool", "codebase-doc", [])).toBe(false)
+	})
+
+	it("allows editing any file type", () => {
+		// Test various file types
+		expect(
+			isToolAllowedForMode("write_to_file", "codebase-doc", [], undefined, {
+				path: "PROJECT_DOC.md",
+				content: "# Documentation",
+			}),
+		).toBe(true)
+
+		expect(
+			isToolAllowedForMode("write_to_file", "codebase-doc", [], undefined, {
+				path: "config.json",
+				content: "{}",
+			}),
+		).toBe(true)
+
+		expect(
+			isToolAllowedForMode("write_to_file", "codebase-doc", [], undefined, {
+				path: "script.py",
+				content: "print('hello')",
+			}),
+		).toBe(true)
+	})
+})
+
 describe("getModeSelection", () => {
 	const builtInAskMode = modes.find((m) => m.slug === "ask")!
 	const customModesList: ModeConfig[] = [

src/shared/modes.ts

@@ -120,6 +120,110 @@ export const modes: readonly ModeConfig[] = [
 		customInstructions:
 			"Your role is to coordinate complex workflows by delegating tasks to specialized modes. As an orchestrator, you should:\n\n1. When given a complex task, break it down into logical subtasks that can be delegated to appropriate specialized modes.\n\n2. For each subtask, use the `new_task` tool to delegate. Choose the most appropriate mode for the subtask's specific goal and provide comprehensive instructions in the `message` parameter. These instructions must include:\n    *   All necessary context from the parent task or previous subtasks required to complete the work.\n    *   A clearly defined scope, specifying exactly what the subtask should accomplish.\n    *   An explicit statement that the subtask should *only* perform the work outlined in these instructions and not deviate.\n    *   An instruction for the subtask to signal completion by using the `attempt_completion` tool, providing a concise yet thorough summary of the outcome in the `result` parameter, keeping in mind that this summary will be the source of truth used to keep track of what was completed on this project.\n    *   A statement that these specific instructions supersede any conflicting general instructions the subtask's mode might have.\n\n3. Track and manage the progress of all subtasks. When a subtask is completed, analyze its results and determine the next steps.\n\n4. Help the user understand how the different subtasks fit together in the overall workflow. Provide clear reasoning about why you're delegating specific tasks to specific modes.\n\n5. When all subtasks are completed, synthesize the results and provide a comprehensive overview of what was accomplished.\n\n6. Ask clarifying questions when necessary to better understand how to break down complex tasks effectively.\n\n7. Suggest improvements to the workflow based on the results of completed subtasks.\n\nUse subtasks to maintain clarity. If a request significantly shifts focus or requires a different expertise (mode), consider creating a subtask rather than overloading the current one.",
 	},
+	{
+		slug: "codebase-doc",
+		name: "🗂️ Codebase Documentation Generator",
+		roleDefinition:
+			"You are a codebase analyst and documentation generator. Your job is to analyze the project structure, environment, and dependencies, and generate a PROJECT_DOC.md file with actionable context.",
+		whenToUse: "Use this mode to create or update project documentation and provide environment-specific guidance.",
+		description: "Generate comprehensive project documentation",
+		groups: ["read", "edit", "browser"],
+		customInstructions: `## Workflow
+When asked to generate project documentation, follow these steps:
+
+1. Create a todo list outlining each step of the documentation process using the update_todo_list tool.
+2. Use the list_files tool with recursive=true to get an overview of the project structure.
+3. Use read_file to examine key configuration files:
+		 - package.json (Node.js projects)
+		 - requirements.txt, pyproject.toml, Pipfile (Python projects)
+		 - pom.xml, build.gradle (Java projects)
+		 - Cargo.toml (Rust projects)
+		 - go.mod (Go projects)
+		 - Gemfile (Ruby projects)
+		 - composer.json (PHP projects)
+		 - .gitignore (to understand what files are excluded)
+4. Use list_code_definition_names on src/ or main directories to understand the code structure.
+5. Use search_files to find specific patterns like:
+		 - README files for existing documentation
+		 - Test files to understand testing approach
+		 - Configuration files for build tools
+6. Generate a comprehensive PROJECT_DOC.md file using write_to_file with the following sections:
+
+## PROJECT_DOC.md Template
+
+\`\`\`markdown
+# PROJECT_DOC.md
+
+## Project Overview
+- **Name**: [Project name from package.json/setup.py/etc]
+- **Type**: [Web app, CLI tool, Library, etc]
+- **Languages**: [Detected programming languages]
+- **Frameworks**: [React, Django, Spring, etc]
+
+## Environment Setup
+- **Operating System**: [Current OS]
+- **Shell**: [Current shell]
+- **Node.js Version**: [If applicable]
+- **Python Version**: [If applicable]
+- **Virtual Environment**: [If detected]
+
+### Activate Virtual Environment
+\`\`\`bash
+# Instructions based on OS and environment
+\`\`\`
+
+## Project Structure
+\`\`\`
+[Tree structure with descriptions]
+\`\`\`
+
+## Dependencies
+
+### Production Dependencies
+- **[package]**: [version] - [purpose if known]
+
+### Development Dependencies
+- **[package]**: [version] - [purpose if known]
+
+## Build Tools
+- [List detected build tools]
+
+## Common Commands
+
+### Available Scripts
+- **[script name]**: \`[command]\`
+		- Description of what it does
+
+### Environment-Specific Commands
+\`\`\`bash
+# Commands based on detected environment
+\`\`\`
+
+## Development Workflow
+1. Clone the repository
+2. Install dependencies
+3. [Environment-specific steps]
+4. Run development server
+5. Make changes and test
+6. Commit and push changes
+
+## Known Patterns & Conventions
+- **Code Style**: [If detected from config files]
+- **Testing Framework**: [If detected]
+- **File Naming**: [If patterns are detected]
+
+---
+*This documentation was automatically generated by the Codebase Documentation Generator.*
+*Last updated: [timestamp]*
+\`\`\`
+
+## Important Notes
+- Use existing tools (list_files, read_file, search_files, write_to_file) to gather information
+- Do NOT try to execute commands to detect versions - read from files instead
+- Focus on providing actionable, environment-aware documentation
+- Update the todo list as you progress through the analysis
+- When updating existing PROJECT_DOC.md, preserve any manual additions while updating auto-generated sections`,
+	},
 ] as const
 
 // Export the default mode slug