ECC: Instructions file for Kiro

Lessons Learned

This file captures project-specific patterns, coding preferences, common pitfalls, and architectural decisions that emerge during development. It serves as a workaround for continuous learning by allowing you to document patterns manually.

How to use this file:

1. The extract-patterns hook will suggest patterns after agent sessions
2. Review suggestions and add genuinely useful patterns below
3. Edit this file directly to capture team conventions
4. Keep it focused on project-specific insights, not general best practices

---

Project-Specific Patterns

Document patterns unique to this project that the team should follow.

Example: API Error Handling

// Always use our custom ApiError class for consistent error responses
throw new ApiError(404, 'Resource not found', { resourceId });

---

Code Style Preferences

Document team preferences that go beyond standard linting rules.

Example: Import Organization

// Group imports: external, internal, types
import { useState } from 'react';
import { Button } from '@/components/ui';
import type { User } from '@/types';

---

Kiro Hooks

install.sh is additive-only — it won't update existing installations

The installer skips any file that already exists in the target (if [ ! -f ... ]). Running it against a folder that already has .kiro/ will not overwrite or update hooks, agents, or steering files. To push updates to an existing project, manually copy the changed files or remove the target files first before re-running the installer.

README.md mirrors hook configurations — keep them in sync

The hooks table and Example 5 in README.md document the action type (runCommand vs askAgent) and behavior of each hook. When changing a hook's then.type or behavior, update both the hook file and the corresponding README entries to avoid misleading documentation.

Prefer askAgent over runCommand for file-event hooks

runCommand hooks on fileEdited or fileCreated events spawn a new terminal session every time they fire, creating friction. Use askAgent instead so the agent handles the task inline. Reserve runCommand for userTriggered hooks where a manual, isolated terminal run is intentional (e.g., quality-gate).