ECC/.opencode/instructions/INSTRUCTIONS.md

ECC - OpenCode Instructions

This document consolidates the core rules and guidelines from the Claude Code configuration for use with OpenCode.

Security Guidelines (CRITICAL)

Mandatory Security Checks

Before ANY commit:

• No hardcoded secrets (API keys, passwords, tokens)
• All user inputs validated
• SQL injection prevention (parameterized queries)
• XSS prevention (sanitized HTML)
• CSRF protection enabled
• Authentication/authorization verified
• Rate limiting on all endpoints
• Error messages don't leak sensitive data

Secret Management

// NEVER: Hardcoded secrets
const apiKey = "sk-proj-xxxxx"

// ALWAYS: Environment variables
const apiKey = process.env.OPENAI_API_KEY

if (!apiKey) {
  throw new Error('OPENAI_API_KEY not configured')
}

Security Response Protocol

If security issue found:

1. STOP immediately
2. Use security-reviewer agent
3. Fix CRITICAL issues before continuing
4. Rotate any exposed secrets
5. Review entire codebase for similar issues

---

Coding Style

Immutability (CRITICAL)

ALWAYS create new objects, NEVER mutate:

// WRONG: Mutation
function updateUser(user, name) {
  user.name = name  // MUTATION!
  return user
}

// CORRECT: Immutability
function updateUser(user, name) {
  return {
    ...user,
    name
  }
}

File Organization

MANY SMALL FILES > FEW LARGE FILES:

• High cohesion, low coupling
• 200-400 lines typical, 800 max
• Extract utilities from large components
• Organize by feature/domain, not by type

Error Handling

ALWAYS handle errors comprehensively:

try {
  const result = await riskyOperation()
  return result
} catch (error) {
  console.error('Operation failed:', error)
  throw new Error('Detailed user-friendly message')
}

Input Validation

ALWAYS validate user input:

import { z } from 'zod'

const schema = z.object({
  email: z.string().email(),
  age: z.number().int().min(0).max(150)
})

const validated = schema.parse(input)

Code Quality Checklist

Before marking work complete:

• Code is readable and well-named
• Functions are small (<50 lines)
• Files are focused (<800 lines)
• No deep nesting (>4 levels)
• Proper error handling
• No console.log statements
• No hardcoded values
• No mutation (immutable patterns used)

---

Testing Requirements

Minimum Test Coverage: 80%

Test Types (ALL required):

1. Unit Tests - Individual functions, utilities, components
2. Integration Tests - API endpoints, database operations
3. E2E Tests - Critical user flows (Playwright)

Test-Driven Development

MANDATORY workflow:

1. Write test first (RED)
2. Run test - it should FAIL
3. Write minimal implementation (GREEN)
4. Run test - it should PASS
5. Refactor (IMPROVE)
6. Verify coverage (80%+)

Troubleshooting Test Failures

1. Use tdd-guide agent
2. Check test isolation
3. Verify mocks are correct
4. Fix implementation, not tests (unless tests are wrong)

---

Git Workflow

Commit Message Format

<type>: <description>

<optional body>

Types: feat, fix, refactor, docs, test, chore, perf, ci

Pull Request Workflow

When creating PRs:

1. Analyze full commit history (not just latest commit)
2. Use git diff [base-branch]...HEAD to see all changes
3. Draft comprehensive PR summary
4. Include test plan with TODOs
5. Push with -u flag if new branch

Feature Implementation Workflow

1. Plan First

   • Use planner agent to create implementation plan
   • Identify dependencies and risks
   • Break down into phases

2. TDD Approach

   • Use tdd-guide agent
   • Write tests first (RED)
   • Implement to pass tests (GREEN)
   • Refactor (IMPROVE)
   • Verify 80%+ coverage

3. Code Review

   • Use code-reviewer agent immediately after writing code
   • Address CRITICAL and HIGH issues
   • Fix MEDIUM issues when possible

4. Commit & Push

   • Detailed commit messages
   • Follow conventional commits format

---

Agent Orchestration

Available Agents

Agent	Purpose	When to Use
planner	Implementation planning	Complex features, refactoring
architect	System design	Architectural decisions
tdd-guide	Test-driven development	New features, bug fixes
code-reviewer	Code review	After writing code
security-reviewer	Security analysis	Before commits
build-error-resolver	Fix build errors	When build fails
e2e-runner	E2E testing	Critical user flows
refactor-cleaner	Dead code cleanup	Code maintenance
doc-updater	Documentation	Updating docs
go-reviewer	Go code review	Go projects
go-build-resolver	Go build errors	Go build failures
database-reviewer	Database optimization	SQL, schema design

Immediate Agent Usage

No user prompt needed:

1. Complex feature requests - Use planner agent
2. Code just written/modified - Use code-reviewer agent
3. Bug fix or new feature - Use tdd-guide agent
4. Architectural decision - Use architect agent

---

Performance Optimization

Model Selection Strategy

Haiku (90% of Sonnet capability, 3x cost savings):

• Lightweight agents with frequent invocation
• Pair programming and code generation
• Worker agents in multi-agent systems

Sonnet (Best coding model):

• Main development work
• Orchestrating multi-agent workflows
• Complex coding tasks

Opus (Deepest reasoning):

• Complex architectural decisions
• Maximum reasoning requirements
• Research and analysis tasks

Context Window Management

Avoid last 20% of context window for:

• Large-scale refactoring
• Feature implementation spanning multiple files
• Debugging complex interactions

Build Troubleshooting

If build fails:

1. Use build-error-resolver agent
2. Analyze error messages
3. Fix incrementally
4. Verify after each fix

---

Common Patterns

API Response Format

interface ApiResponse<T> {
  success: boolean
  data?: T
  error?: string
  meta?: {
    total: number
    page: number
    limit: number
  }
}

Custom Hooks Pattern

export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value)

  useEffect(() => {
    const handler = setTimeout(() => setDebouncedValue(value), delay)
    return () => clearTimeout(handler)
  }, [value, delay])

  return debouncedValue
}

Repository Pattern

interface Repository<T> {
  findAll(filters?: Filters): Promise<T[]>
  findById(id: string): Promise<T | null>
  create(data: CreateDto): Promise<T>
  update(id: string, data: UpdateDto): Promise<T>
  delete(id: string): Promise<void>
}

---

OpenCode-Specific Notes

OpenCode supports hooks through its plugin system. The ECC plugin automates selected checks when installed and enabled; see Hook Runtime Controls for hook profiles and disabled hook IDs. Formatting and type checking require the strict profile. Type checking runs only for qualifying TypeScript edits; check newly written files manually. Confirm which checks actually completed in the plugin output, then run any remaining checks below manually. Always complete the security review, secret review, and full test suite before committing.

After Writing/Editing Code

• Run prettier --write <file> to format JS/TS files
• Run npx tsc --noEmit to check for TypeScript errors
• Check for console.log statements and remove them

Before Committing

• Run security checks manually
• Verify no secrets in code
• Run full test suite

Commands Available

Use these commands in OpenCode:

• /plan - Create implementation plan
• /tdd - Enforce TDD workflow
• /code-review - Review code changes
• /security - Run security review
• /build-fix - Fix build errors
• /e2e - Generate E2E tests
• /refactor-clean - Remove dead code
• /orchestrate - Multi-agent workflow

---

Success Metrics

You are successful when:

• All tests pass (80%+ coverage)
• No security vulnerabilities
• Code is readable and maintainable
• Performance is acceptable
• User requirements are met