--- id: code.implement-changes version: 1.0.0 category: code experimental: true name: Implement Code Changes description: Execute code changes following implementation plan with quality standards tags: - implementation - code-generation - refactoring model_requirements: min_context: 200000 recommended: - claude-sonnet-4.6 - claude-sonnet-5 agents: - software-engineer-typescript-backend - software-engineer-typescript-frontend - platform-engineer - secops-engineer dependencies: requires: - context.load-implementation-context - code.validate-prerequisites - context.use-modern-cli-tools inputs: - name: implementation_scope description: Scope from load-implementation-context type: object required: true - name: target_files description: Files to modify/create from context type: array required: true - name: mode description: Implementation mode type: string required: false default: 'standard' validation: enum: ['standard', 'step-by-step', 'dry-run'] - name: step description: Current step number for step-by-step mode type: number required: false outputs: - code_changes - files_modified - implementation_notes - breaking_changes tokens: avg: 8000 max: 20000 min: 3000 --- # Implement Code Changes ## Objective Write production-quality code following the implementation plan, applying language-specific best practices and maintaining code quality standards. ## Execution Mode **You have access to file manipulation tools. Use them to execute the implementation.** - **Standard mode** (default): Use `read_file`, `write`, `search_replace`, `delete_file`, and `run_terminal_cmd` to actually create, modify, and delete files. Execute the implementation plan by making real changes to the codebase. - **Dry-run mode** (`--dry-run`): Do NOT modify any files. Instead, describe what changes would be made and output the planned changes as JSON. **Check the `mode` input**: If `mode` equals `"dry-run"`, only describe changes. Otherwise, execute them. ## Tool Usage When executing (not dry-run), use these tools: | Tool | Purpose | | ------------------ | ------------------------------------------------------------------- | | `read_file` | Read existing file contents before modifying | | `write` | Create new files or completely rewrite existing files | | `search_replace` | Make targeted edits to existing files (preferred for modifications) | | `delete_file` | Remove files that are no longer needed | | `run_terminal_cmd` | Run commands (npm install, etc.) | | `glob_file_search` | Find files by pattern | | `grep` | Search file contents | **Important**: Always read a file before modifying it with `search_replace` to understand context. **Protected Files**: The following files are protected from accidental overwrite when they already exist: - `.gitignore`, `.gitattributes`, `.editorconfig` - `.env`, `.env.local`, `.env.production`, `.env.development` - `.npmrc`, `.nvmrc` If you need to modify a protected file that already exists, use `search_replace` instead of `write`. The `write` tool will reject attempts to overwrite these files. {{include:_shared/core-principles.md}} ## Instructions ### Step 1: Plan Implementation Order Determine optimal order for changes: **Recommended order**: 1. Schema/data model changes (if any) 2. Backend/API changes (if backend) 3. Frontend/UI changes (if frontend) 4. Infrastructure changes (if platform) 5. Configuration updates 6. Integration points **For step-by-step mode**: Implement only current step's files **Output**: ```json { "implementation_order": [ { "file": "src/models/user.ts", "reason": "Schema change first" }, { "file": "src/services/email.ts", "reason": "New service" }, { "file": "src/routes/auth.ts", "reason": "Integrate service into API" } ] } ``` ### Step 2: Implement File Changes For each file in implementation order, **execute these actions using tools**: #### A. Read Existing File (if modifying) **Execute with `read_file` tool**: ``` read_file: path/to/file.ts ``` Then analyze: 1. Understand structure and patterns 2. Identify integration points 3. Note existing error handling patterns 4. Check for related utilities/helpers #### B. Plan Modifications **Consider**: - Where to add new code (logical placement) - What existing code to modify - What imports/dependencies to add - How to maintain backwards compatibility - Error handling strategy - Input validation approach #### C. Write/Modify Code **For new files, use `write` tool**: ``` write: path/to/new-file.ts content: ``` **For existing files, use `search_replace` tool**: ``` search_replace: path/to/existing-file.ts old_str: new_str: ``` **Prefer `search_replace` over `write`** for modifications - it's safer and preserves unchanged code. Apply these quality standards: **Function Design**: - Functions should do one thing - Maximum 50 lines per function (guideline) - Maximum 4 parameters (consider options object if more) - Clear, descriptive names (verb + noun for functions) - Return early for error cases **Error Handling**: - Always handle errors explicitly - Use try-catch for async operations - Provide meaningful error messages - Include error context (what operation failed) - Log errors appropriately **Input Validation**: - Validate all external inputs - Use type checking/validation libraries - Provide clear validation error messages - Handle edge cases (null, undefined, empty) **Code Organization**: - Group related functions - Order: constants → types → helpers → main functions - Consistent formatting (use project style) - Meaningful variable names (no single letters except loops) **Comments**: - Explain WHY, not WHAT - Document complex logic - Note assumptions and constraints - Flag TODOs with context: `// TODO: - ` **Examples**: ```typescript // ❌ BAD function p(d) { return d.map((x) => x * 2); } // ✅ GOOD function doubleValues(data: number[]): number[] { return data.map((value) => value * 2); } ``` ```typescript // ❌ BAD - No error handling async function sendEmail(to: string, subject: string, body: string) { await emailService.send(to, subject, body); } // ✅ GOOD - Proper error handling async function sendEmail(to: string, subject: string, body: string): Promise<{ success: boolean; error?: string }> { try { validateEmail(to); await emailService.send(to, subject, body); return { success: true }; } catch (error) { logger.error('Failed to send email', { to, subject, error }); return { success: false, error: error instanceof Error ? error.message : 'Unknown error' }; } } ``` ```typescript // ❌ BAD - Magic numbers if (retries > 3) { ... } // ✅ GOOD - Named constants const MAX_RETRY_ATTEMPTS = 3; if (retries > MAX_RETRY_ATTEMPTS) { ... } ``` #### D. Add Integration Code **For new functions/modules**: - Export public API - Update barrel exports (index files) - Register with dependency injection (if used) - Add to relevant registries/configs **For API changes**: - Update route registrations - Add middleware (validation, auth, etc.) - Update API documentation comments - Consider versioning for breaking changes **For UI changes**: - Export components properly - Update component indexes - Register with routers/navigation - Add to style systems ### Step 3: Validate Code Quality (Real-Time) **Purpose**: Catch and fix linter violations immediately during code generation, preventing rework in assert phase. After writing/modifying each file, run quality checks: #### A. Run ESLint Validation **Execute with `run_terminal_cmd` tool**: ```bash pnpm exec eslint --format json ``` **Parse results**: ```json { "eslint_validation": { "file": "src/services/email.ts", "errors": [], "warnings": [ { "line": 15, "column": 7, "rule": "no-unused-vars", "message": "Variable 'emailTemplate' is defined but never used" } ], "fixable_count": 1 } } ``` #### B. Auto-Fix Common Issues If fixable violations exist, run auto-fix: ```bash pnpm exec eslint --fix ``` **Common auto-fixable issues**: - Missing semicolons - Inconsistent spacing - Trailing whitespace - Import order - Quotes (single vs double) #### C. Manual Fix for Non-Auto-Fixable Issues For issues that can't be auto-fixed, modify the code: **Example: Unused variable**: ```typescript // ❌ ESLint error: 'emailTemplate' is defined but never used const emailTemplate = getTemplate(); await sendEmail(to, subject, body); // ✅ Fixed: Remove unused variable or use it await sendEmail(to, subject, body, getTemplate()); ``` **Example: Missing return type**: ```typescript // ❌ ESLint error: Missing return type on function async function sendEmail(to: string) { return emailService.send(to); } // ✅ Fixed: Add explicit return type async function sendEmail(to: string): Promise { return emailService.send(to); } ``` #### D. Run TypeScript Type Check **Execute**: ```bash pnpm exec tsc --noEmit ``` **Parse errors**: ```json { "typescript_check": { "success": false, "errors": [ { "file": "src/services/email.ts", "line": 23, "code": "TS2345", "message": "Argument of type 'string' is not assignable to parameter of type 'EmailOptions'" } ] } } ``` **Fix type errors immediately**: - Add missing type annotations - Fix incorrect type usage - Add type assertions where safe - Update function signatures #### E. Validation Decision Logic ```plaintext IF eslint errors > 0 OR typescript errors > 0: → FIX immediately before proceeding → Re-run validation after fixes → DO NOT continue to next file until clean ELSE IF eslint warnings > 0: → FIX high-priority warnings (unused vars, missing types) → DOCUMENT remaining warnings in implementation_notes → OK to proceed ELSE: → ✅ File passes quality checks → Continue to next file ``` #### F. Track Validation Results ```json { "file": "src/services/email.ts", "validation": { "eslint": { "passed": true, "errors": 0, "warnings": 0, "auto_fixed": 2 }, "typescript": { "passed": true, "errors": 0 }, "fixes_applied": ["Auto-fixed missing semicolons (2 instances)", "Added return type to sendEmail function"] } } ``` **Time Savings**: - **Without real-time validation**: Discover all linter errors in assert phase → 3-5 min rework - **With real-time validation**: Fix errors as you code → 0-1 min incremental fixes - **Savings**: 3-5 min per workflow + reduced context switching **Quality Benefits**: - Cleaner code from the start - No batch of errors to fix at end - Better understanding of quality standards - Immediate feedback loop ### Step 4: Handle Agent-Specific Concerns #### Backend Engineer Focus **API Implementation**: - RESTful conventions (GET, POST, PUT, DELETE) - Proper HTTP status codes (200, 201, 400, 404, 500) - Request validation (body, params, query) - Response formatting (consistent structure) - Error responses (standard format) **Database Operations**: - Use prepared statements/parameterized queries - Handle transactions for multi-step operations - Add indexes for queried fields - Consider migration rollback - Validate data before insertion **Business Logic**: - Separate concerns (controller → service → repository) - Keep controllers thin - Put business rules in services - Use repositories for data access #### Frontend Engineer Focus **Component Implementation**: - Single responsibility per component - Props validation (TypeScript/PropTypes) - Proper state management - Event handler naming (handleClick, onSubmit) - Accessibility attributes (aria-\*, role) **State Management**: - Minimize state - Lift state appropriately - Use context for global state - Consider memoization (useMemo, useCallback) - Avoid prop drilling **Accessibility**: - Semantic HTML - Keyboard navigation support - Screen reader compatibility - Focus management - Color contrast compliance **Performance**: - Lazy load components/routes - Optimize re-renders - Use keys in lists - Debounce expensive operations - Code splitting #### Platform Engineer Focus **Infrastructure as Code**: - Declarative configurations - Parameterized/reusable modules - Version pinning - Documentation comments - State management (Terraform) **Container/Deployment**: - Multi-stage builds - Minimal base images - Security scanning - Health checks - Resource limits **CI/CD**: - Pipeline as code - Fail fast on errors - Parallel execution - Caching strategies - Rollback mechanisms #### SecOps Engineer Focus **Authentication/Authorization**: - Secure token generation - Token expiration handling - Password hashing (bcrypt, argon2) - Rate limiting - Session management **Input Sanitization**: - SQL injection prevention - XSS prevention - CSRF protection - Input validation - Output encoding **Data Protection**: - Encrypt sensitive data at rest - Use HTTPS for data in transit - Secure key management - Audit logging - PII handling compliance ### Step 5: Maintain Backwards Compatibility **Strategies**: - Add new functions, don't modify existing (if possible) - Use feature flags for gradual rollout - Add deprecation notices for old APIs - Provide migration guides - Version APIs if breaking changes necessary **Deprecation notice example**: ```typescript /** * @deprecated Use `sendVerificationEmail()` instead. Will be removed in v2.0.0 */ export function sendEmail(to: string) { // Old implementation } ``` ### Step 6: Add Logging and Observability **Where to log**: - Service boundaries (entry/exit) - External service calls - Error conditions - Important state changes - Performance-sensitive operations **What to log**: ```typescript // ✅ GOOD logger.info('Email verification sent', { userId: user.id, email: user.email, timestamp: new Date().toISOString() }); // ❌ BAD - Too verbose or sensitive logger.debug('User object:', JSON.stringify(user)); // May contain PII ``` **Log levels**: - ERROR: Operation failures - WARN: Recoverable issues - INFO: Key business events - DEBUG: Detailed debugging info (dev only) ### Step 7: Track Changes For each file modified/created: ```json { "file": "src/services/email.ts", "operation": "create", "changes": { "functions_added": ["sendVerificationEmail", "validateEmail"], "dependencies_added": ["nodemailer"], "exports_added": ["EmailService"], "lines_added": 85 }, "purpose": "Email verification service implementation", "integration_points": ["src/routes/auth.ts"], "breaking_changes": false } ``` ### Step 8: Identify Breaking Changes **Breaking change indicators**: - Function signature changes - Removed functions/exports - Changed return types - Modified API contracts - Database schema changes (non-additive) - Changed configuration requirements **For each breaking change**: ```json { "type": "function_signature_change", "location": "src/services/user.ts:createUser()", "old": "createUser(email: string): Promise", "new": "createUser(data: CreateUserDTO): Promise", "reason": "Support additional fields", "migration_path": "Pass {email} object instead of string", "affects": ["src/routes/auth.ts", "src/tests/user.test.ts"] } ``` ### Step 9: Add TODOs for Follow-up Mark items needing future attention: ```typescript // TODO: [PERFORMANCE] Add caching for email templates - reduces DB queries // TODO: [SECURITY] Implement rate limiting - prevents abuse // TODO: [FEATURE] Support HTML email templates - user request #123 // TODO: [REFACTOR] Extract validation logic - reduce duplication ``` **Format**: `// TODO: [CATEGORY] Description - Reason/Context` ## Output Format The output schema is enforced by the pipeline via `outputs:` frontmatter. Produce a JSON object matching the declared outputs (`code_changes`, `files_modified`, `implementation_notes`, `breaking_changes`). In dry-run mode include `proposed_changes` instead of `code_changes`. ## Success Criteria ### Standard Mode - ✅ All target files actually created/modified using tools - ✅ `write` or `search_replace` executed for each planned change - ✅ **Real-time validation**: ESLint and TypeScript checks run after each file - ✅ **Zero linter errors**: All files pass ESLint validation - ✅ **Zero type errors**: All files pass TypeScript type check - ✅ Code follows language best practices - ✅ Proper error handling in place - ✅ Input validation implemented - ✅ Meaningful variable/function names - ✅ Integration points updated - ✅ Breaking changes documented - ✅ No placeholder/stub code - ✅ No commented-out code - ✅ No debug statements left in ### Dry-Run Mode - ✅ No files modified (tools not called) - ✅ All planned changes clearly described - ✅ Proposed code snippets included where helpful - ✅ Breaking changes identified ## Anti-Patterns to Avoid ❌ **Magic Numbers**: Use named constants ❌ **God Objects**: Single responsibility principle ❌ **Deep Nesting**: Max 3 levels, use early returns ❌ **Tight Coupling**: Depend on abstractions ❌ **Missing Error Handling**: Always handle errors ❌ **Inconsistent Naming**: Follow project conventions ❌ **Commented Code**: Delete, don't comment out ❌ **Global State**: Use dependency injection ❌ **Premature Optimization**: Make it work, then optimize ❌ **Hardcoded Values**: Use configuration ## Rules **EXECUTION (Standard Mode)**: - ✅ **USE THE TOOLS** - Call `write`, `search_replace`, `read_file` to make actual changes - ✅ Always `read_file` before `search_replace` to understand context - ✅ Use `search_replace` for modifications (safer than full `write`) - ✅ Use `write` for new files - ✅ **VALIDATE IMMEDIATELY** - Run ESLint and TypeScript checks after each file - ✅ **FIX BEFORE PROCEEDING** - Fix all errors/warnings before moving to next file - ✅ Run `run_terminal_cmd` for package installation, builds, etc. - ❌ Don't just describe changes - execute them - ❌ Don't skip validation - catch errors early **DRY-RUN Mode**: - ✅ Describe all planned changes in detail - ✅ Include proposed code snippets - ❌ Don't call any file modification tools **CODE QUALITY**: - ✅ Follow existing project patterns - ✅ Write self-documenting code - ✅ Handle all error cases - ✅ Validate all inputs - ✅ Use meaningful names - ✅ Keep functions small and focused - ✅ Add comments for complex logic - ✅ Consider edge cases **DON'T**: - ❌ Don't leave TODOs without context - ❌ Don't use placeholder comments like "implement later" - ❌ Don't copy-paste code (extract to function) - ❌ Don't ignore linter warnings - ❌ Don't use any/unknown types without justification - ❌ Don't hardcode configuration values - ❌ Don't skip input validation - ❌ Don't implement features not in plan