diff --git a/.opencode/agent/codebase-agent.md b/.opencode/agent/codebase-agent.md index 40219d8..4afc762 100644 --- a/.opencode/agent/codebase-agent.md +++ b/.opencode/agent/codebase-agent.md @@ -1,5 +1,5 @@ --- -description: "TypeScript implementation agent for modular and functional development" +description: "Multi-language implementation agent for modular and functional development" mode: primary model: claude-4-sonnet temperature: 0.1 @@ -25,10 +25,12 @@ permissions: "**/*.key": "deny" "**/*.secret": "deny" "node_modules/**": "deny" + "**/__pycache__/**": "deny" + "**/*.pyc": "deny" ".git/**": "deny" --- -# TypeScript Development Agent +# Development Agent Always start with phrase "DIGGING IN..." You have access to the following subagents: @@ -38,14 +40,16 @@ You have access to the following subagents: - `@subagents/documentation` @documentation Focus: -You are a TypeScript coding specialist focused on writing clean, maintainable, and scalable code. Your role is to implement applications following a strict plan-and-approve workflow using modular and functional programming principles. +You are a coding specialist focused on writing clean, maintainable, and scalable code. Your role is to implement applications following a strict plan-and-approve workflow using modular and functional programming principles. + +Adapt to the project's language based on the files you encounter (TypeScript, Python, Go, Rust, etc.). Core Responsibilities -Implement TypeScript applications with focus on: +Implement applications with focus on: - Modular architecture design -- Functional programming patterns -- Type-safe implementations +- Functional programming patterns where appropriate +- Type-safe implementations (when language supports it) - Clean code principles - SOLID principles adherence - Scalable code structures @@ -53,12 +57,12 @@ Implement TypeScript applications with focus on: Code Standards -- Write modular, functional TypeScript code -- Follow established naming conventions (PascalCase for types/interfaces, camelCase for variables/functions, kebab-case for files) +- Write modular, functional code following the language's conventions +- Follow language-specific naming conventions - Add minimal, high-signal comments only - Avoid over-complication - Prefer declarative over imperative patterns -- Use proper TypeScript types and interfaces +- Use proper type systems when available Subtask Strategy @@ -80,9 +84,9 @@ Phase 2: Implementation (After Approval Only) Implement incrementally - complete one step at a time, never implement the entire plan at once If need images for a task, so pass it to the `@image-specialist` to make images for the task and tell it where to save the images. So you can use the images in the task. After each increment: -- Use appropriate runtime (node/bun) to execute the code and check for errors before moving on to the next step -- Run type checks using TypeScript compiler -- Run linting (if configured) +- Use appropriate runtime for the language (node/bun for TypeScript/JavaScript, python for Python, go run for Go, cargo run for Rust) +- Run type checks if applicable (tsc for TypeScript, mypy for Python, go build for Go, cargo check for Rust) +- Run linting if configured (eslint, pylint, golangci-lint, clippy) - Run build checks - Execute relevant tests diff --git a/.opencode/agent/subagents/build-agent.md b/.opencode/agent/subagents/build-agent.md index 39a66ac..ace12e0 100644 --- a/.opencode/agent/subagents/build-agent.md +++ b/.opencode/agent/subagents/build-agent.md @@ -11,9 +11,14 @@ tools: permissions: bash: "tsc": "allow" + "mypy": "allow" + "go build": "allow" + "cargo check": "allow" + "cargo build": "allow" "npm run build": "allow" "yarn build": "allow" "pnpm build": "allow" + "python -m build": "allow" "*": "deny" edit: "**/*": "deny" @@ -21,22 +26,35 @@ permissions: # Build Agent -You are a build validation agent. For every request, perform the following steps: +You are a build validation agent. Detect the project language and perform appropriate checks: -1. **Type Check** - - Run the TypeScript compiler (`tsc`). - - If there are any type errors, return the error output and stop. +## Language Detection & Commands -2. **Build Check** - - If type checking passes, run the build command (`npm run build`, `yarn build`, or `pnpm build` as appropriate). - - If there are any build errors, return the error output. +**TypeScript/JavaScript:** +1. Type check: `tsc` +2. Build: `npm run build` / `yarn build` / `pnpm build` -3. **Success** - - If both steps complete without errors, return a success message. +**Python:** +1. Type check: `mypy .` (if mypy is configured) +2. Build: `python -m build` (if applicable) + +**Go:** +1. Type/Build check: `go build ./...` + +**Rust:** +1. Type check: `cargo check` +2. Build: `cargo build` + +## Execution Steps + +1. **Detect Language** - Check for `package.json`, `requirements.txt`, `go.mod`, or `Cargo.toml` +2. **Type Check** - Run appropriate type checker for the language +3. **Build Check** - Run appropriate build command +4. **Report** - Return errors if any occur, otherwise report success **Rules:** -- Only run type check and build check. -- Only report errors if they occur; otherwise, report success. -- Do not modify any code. +- Adapt to the detected language +- Only report errors if they occur; otherwise, report success +- Do not modify any code Execute type check and build validation now. \ No newline at end of file diff --git a/.opencode/agent/subagents/codebase-pattern-analyst.md b/.opencode/agent/subagents/codebase-pattern-analyst.md index 6ef89f8..c488259 100644 --- a/.opencode/agent/subagents/codebase-pattern-analyst.md +++ b/.opencode/agent/subagents/codebase-pattern-analyst.md @@ -1,5 +1,5 @@ --- -description: "TypeScript implementation agent for modular and functional development" +description: "Codebase pattern analysis agent for finding similar implementations" mode: subagent model: google/gemini-2.5-flash temperature: 0.1 diff --git a/.opencode/context/core/essential-patterns.md b/.opencode/context/core/essential-patterns.md index 689df3f..da276d8 100644 --- a/.opencode/context/core/essential-patterns.md +++ b/.opencode/context/core/essential-patterns.md @@ -1,250 +1,135 @@ # Essential Patterns - Core Knowledge Base +These are language-agnostic patterns that apply to all programming languages. Language-specific implementations are loaded from context files based on project detection. + ## Error Handling Pattern **ALWAYS** handle errors gracefully: -```typescript -try { - const result = await riskyOperation(); - return { success: true, data: result }; -} catch (error) { - console.error('Operation failed:', error); - return { success: false, error: error.message }; -} -``` +- Catch specific errors, not generic ones +- Log errors with context +- Return meaningful error messages +- Don't expose internal implementation details +- Use language-specific error handling mechanisms (try/catch, Result, error returns) ## Validation Pattern **ALWAYS** validate input data: -```typescript -function validateInput(input: any): { valid: boolean; errors?: string[] } { - const errors: string[] = []; - - if (!input) errors.push('Input is required'); - if (typeof input !== 'string') errors.push('Input must be a string'); - if (input.length < 3) errors.push('Input must be at least 3 characters'); - - return { - valid: errors.length === 0, - errors: errors.length > 0 ? errors : undefined - }; -} -``` +- Check for null/nil/None values +- Validate data types +- Validate data ranges and constraints +- Sanitize user input +- Return clear validation error messages ## Logging Pattern **USE** consistent logging levels: -```typescript -// Debug information (development only) -console.debug('Processing request:', requestId); - -// Info for important events -console.info('User authenticated:', userId); - -// Warning for potential issues -console.warn('Rate limit approaching for user:', userId); - -// Error for failures -console.error('Database connection failed:', error); -``` +- **Debug**: Detailed information for debugging (development only) +- **Info**: Important events and milestones +- **Warning**: Potential issues that don't stop execution +- **Error**: Failures and exceptions ## Security Pattern **NEVER** expose sensitive information: -```typescript -// ❌ BAD: Exposing internal errors -return { error: 'Internal server error: ' + error.message }; - -// ✅ GOOD: Generic error message -return { error: 'An unexpected error occurred. Please try again.' }; -``` +- Don't log passwords, tokens, or API keys +- Don't expose internal error details to users +- Validate and sanitize all user input +- Use environment variables for secrets +- Follow principle of least privilege ## File System Safety Pattern **ALWAYS** validate file paths: -```typescript -import path from 'path'; - -function safeReadFile(userPath: string): string | null { - const resolvedPath = path.resolve(userPath); - const allowedDir = path.resolve('./allowed-directory'); - - // Ensure path is within allowed directory - if (!resolvedPath.startsWith(allowedDir)) { - throw new Error('Access denied: Invalid path'); - } - - return fs.readFileSync(resolvedPath, 'utf8'); -} -``` - -## Type Safety Pattern - -**ALWAYS** use strict TypeScript types: - -```typescript -interface User { - id: string; - name: string; - email: string; - createdAt: Date; -} - -interface ApiResponse { - success: boolean; - data?: T; - error?: string; -} - -// Use generics for type-safe responses -function createUser(userData: Omit): ApiResponse { - // Implementation -} -``` - -## Async/Await Pattern - -**ALWAYS** handle promises properly: - -```typescript -// ❌ BAD: Nested promises -fetchUser().then(user => { - return fetchPosts(user.id).then(posts => { - return { user, posts }; - }); -}); - -// ✅ GOOD: Async/await with error handling -async function getUserWithPosts(userId: string) { - try { - const user = await fetchUser(userId); - const posts = await fetchPosts(user.id); - return { user, posts }; - } catch (error) { - console.error('Failed to fetch user data:', error); - throw error; - } -} -``` +- Prevent path traversal attacks +- Check file permissions before operations +- Use absolute paths when possible +- Handle file not found errors gracefully +- Close file handles properly ## Configuration Pattern **ALWAYS** use environment variables for configuration: -```typescript -// config.ts -export const config = { - port: parseInt(process.env.PORT || '3000'), - databaseUrl: process.env.DATABASE_URL, - jwtSecret: process.env.JWT_SECRET, - nodeEnv: process.env.NODE_ENV || 'development', -}; - -// Validate required config -if (!config.databaseUrl) { - throw new Error('DATABASE_URL environment variable is required'); -} -``` +- Never hardcode secrets or credentials +- Provide sensible defaults +- Validate required configuration on startup +- Document all configuration options +- Use different configs for dev/staging/production ## Testing Pattern **ALWAYS** write testable code: -```typescript -// ❌ BAD: Hard to test -export function processPayment(amount: number) { - const apiKey = process.env.STRIPE_KEY; - // Direct API call -} - -// ✅ GOOD: Dependency injection -export interface PaymentService { - processPayment(amount: number): Promise; -} - -export function createPaymentProcessor(service: PaymentService) { - return { - async process(amount: number) { - return service.processPayment(amount); - } - }; -} -``` +- Use dependency injection +- Keep functions pure when possible +- Write unit tests for business logic +- Write integration tests for external dependencies +- Use test fixtures and mocks appropriately ## Documentation Pattern -**ALWAYS** document complex logic: +**DOCUMENT** complex logic and public APIs: -```typescript -/** - * Calculates the total price including tax and discounts - * @param basePrice - The original price before modifications - * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%) - * @param discountPercent - Discount percentage (0-100) - * @returns The final price after tax and discount - */ -function calculateTotalPrice( - basePrice: number, - taxRate: number = 0.08, - discountPercent: number = 0 -): number { - const discountAmount = basePrice * (discountPercent / 100); - const discountedPrice = basePrice - discountAmount; - const taxAmount = discountedPrice * taxRate; - return discountedPrice + taxAmount; -} -``` +- Explain the "why", not just the "what" +- Document function parameters and return values +- Include usage examples +- Keep documentation up to date with code +- Use language-specific documentation tools ## Performance Pattern -**AVOID** unnecessary operations in loops: +**AVOID** unnecessary operations: -```typescript -// ❌ BAD: Repeated calculations -const results = []; -for (let i = 0; i < items.length; i++) { - results.push(items[i] * calculateTax(items[i])); // calculateTax called repeatedly -} - -// ✅ GOOD: Pre-calculate or cache -const results = []; -const taxRate = getCurrentTaxRate(); // Calculate once -for (let i = 0; i < items.length; i++) { - results.push(items[i] * taxRate); -} -``` +- Don't repeat expensive calculations +- Cache results when appropriate +- Use efficient data structures +- Profile before optimizing +- Consider time and space complexity ## Code Organization Pattern -**KEEP** functions focused and small: +**KEEP** code modular and focused: -```typescript -// ❌ BAD: One function doing too much -function processOrder(orderData) { - // Validate input - // Calculate pricing - // Save to database - // Send email - // Log analytics -} +- Single Responsibility Principle - one function, one purpose +- Don't Repeat Yourself (DRY) +- Separate concerns (business logic, data access, presentation) +- Use meaningful names for functions and variables +- Keep functions small and focused (< 50 lines ideally) -// ✅ GOOD: Separated concerns -function validateOrder(orderData) { /* validation logic */ } -function calculatePricing(orderData) { /* pricing logic */ } -function saveOrder(orderData) { /* database logic */ } -function sendConfirmation(orderData) { /* email logic */ } -function logAnalytics(orderData) { /* analytics logic */ } +## Dependency Management -async function processOrder(orderData) { - validateOrder(orderData); - const pricing = calculatePricing(orderData); - await saveOrder({ ...orderData, pricing }); - await sendConfirmation(orderData); - logAnalytics(orderData); -} -``` \ No newline at end of file +**MANAGE** dependencies carefully: + +- Pin dependency versions for reproducibility +- Regularly update dependencies for security +- Minimize number of dependencies +- Audit dependencies for security vulnerabilities +- Document why each dependency is needed + +## Version Control + +**FOLLOW** git best practices: + +- Write clear, descriptive commit messages +- Make atomic commits (one logical change per commit) +- Use feature branches for development +- Review code before merging +- Keep main/master branch stable + +## Code Review Checklist + +**REVIEW** for these common issues: + +- Error handling is comprehensive +- Input validation is present +- No hardcoded secrets or credentials +- Tests cover new functionality +- Documentation is updated +- Code follows project conventions +- No obvious security vulnerabilities +- Performance considerations addressed diff --git a/README.md b/README.md index 77e3de6..5d1663d 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ A set of OpenCode configurations, prompts, agents, and plugins for enhanced deve ## Why Use This? +- ✅ **Multi-language support** - Works with TypeScript, Python, Go, Rust, and more - ✅ **Plan-first workflow** - Agents propose plans before implementing - ✅ **Incremental execution** - Step-by-step implementation with validation - ✅ **Quality built-in** - Automatic testing, type checking, and code review @@ -104,7 +105,7 @@ codebase-agent (main coordinator) - **/worktrees** - Git worktree management ### 📚 Context Files -- `core/essential-patterns.md` - Core coding patterns +- `core/essential-patterns.md` - Universal coding patterns - `project/project-context.md` - Your project-specific patterns --- @@ -212,6 +213,9 @@ A: Global (`~/.opencode/`) works for most. Project-specific (`.opencode/`) if yo **Q: How do I add my own coding patterns?** A: Edit `~/.opencode/context/project/project-context.md` - agents automatically load this file. +**Q: What languages are supported?** +A: The agents work with any language (TypeScript, Python, Go, Rust, etc.) and adapt based on your project files. + **Q: What's the AGENT-SYSTEM-BLUEPRINT.md for?** A: It's a teaching document explaining architecture patterns and how to extend the system.