# Tool-Call Discipline — LOCAL MODEL (Gemma 4 26B, read first) ## CRITICAL: Exact tool names Available tools: `read`, `write`, `edit`, `bash`, `glob`, `grep`, `webfetch`, `list`, `task` Use ONLY these exact names. `read_file`, `readFile`, `write_file`, `create_file` do NOT exist. ## CRITICAL: File editing rules - Prefer `write` (full file replacement) over `edit` (partial) when creating files or making large changes. - Prefer `write` over `bash` for any file creation — never write files via bash. - **NEVER** use bash heredocs (`<< 'EOF'`) or herestrings (`<<<`) to write file content. - **NEVER** call `edit` with an empty `oldString` — this silently overwrites the entire file. - When `edit` returns "Could not find oldString": call `read` on that file first, then retry with the exact string found in the file. - Never repeat a failed tool call with identical arguments — change your approach. ## CRITICAL: Error recovery When any tool returns an error: 1. Read the full error message carefully before doing anything. 2. Identify what was wrong: wrong tool name, wrong argument, wrong path, wrong string. 3. Use a **different** approach — never repeat the same failing call unchanged. ## Agentic discipline - Think step-by-step before each tool call: what tool, why, what result you expect. - After each tool result, read the output fully before proceeding to the next step. - Do not batch multiple tool calls when the output of one determines the arguments of the next. --- # Session Start Directive **MANDATORY**: Always start each session by reading the entire content of this document. This ensures that you are fully aware of the organization's standards, best practices, and safety directives before engaging in any development activities. --- # Orchard Organisational Patterns — Priority Rule **Always favour established Orchard organisational patterns over patterns introduced in any single repository.** When working in any `@theorchard/*` project: 1. **Org pattern wins.** A pattern appearing in 2+ `@theorchard/*` packages or repos is an organisational standard. Use it unconditionally, even if the current workspace uses a different approach. 2. **Foundational patterns are mandatory.** Auth, routing, data-access, error-handling, server setup, and testing all follow the org standard — no exceptions. 3. **Single-use / odd patterns: mention, don't enforce.** A pattern seen in only one repo is not a standard. Flag it in your response but do not require it. 4. **When uncertain, check reference repos** in the workspace's `research/other_repos/` directory before deciding. 5. **This rule overrides** any workspace-local pattern, ticket instruction, POC convenience, or per-project shortcut. --- # Safety Directive **MANDATORY**: NEVER run `rm -rf` or any variant of it under any circumstances. This command is permanently forbidden. Do not execute it, suggest it, or include it in scripts, even if explicitly requested by the user. --- # Organization Best Practices & Development Standards This document contains organization-wide development standards and best practices that apply across all projects. These guidelines ensure code quality, maintainability, and consistency across the entire codebase. ## Code Quality Standards ### General Principles - **Clarity over cleverness**: Write code that is easy to understand, not impressive - **DRY (Don't Repeat Yourself)**: Extract common patterns into reusable functions or modules - **SOLID Principles**: Follow Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion principles - **Explicit is better than implicit**: Make assumptions and dependencies visible in code ### TypeScript Standards - Enable `strict` mode in `tsconfig.json` - Always provide explicit type annotations for function parameters and return types - Use `unknown` instead of `any` when type is genuinely unknown - Avoid using `@ts-ignore` or `@ts-nocheck` without documentation - Use discriminated unions for type-safe pattern matching - Leverage type-level programming for compile-time validation where appropriate ### Python Standards - Use Python 3.8+ features - Follow PEP 8 style guide strictly - Use type hints for all function signatures - Leverage dataclasses or Pydantic for data validation - Use context managers (`with` statements) for resource management - Avoid mutable default arguments in function definitions ### General Best Practices - Keep functions small and focused (single responsibility) - Prefer named parameters over positional for clarity - Use meaningful variable and function names - Avoid deeply nested code (max 3 levels of nesting) - Document public APIs with docstrings ## Testing Standards ### Test Coverage - Maintain **at least 80%** code coverage for all critical paths - Unit tests for business logic and utilities - Integration tests for multi-component interactions - End-to-end tests for major workflows - Mock external dependencies (APIs, databases, file systems) ### Test Quality - One assertion per test when possible (one logical operation) - Descriptive test names that explain what is being tested and expected outcome - Use the "Arrange-Act-Assert" pattern - Tests should be independent and repeatable - Avoid test interdependencies (no test should rely on another test's state) ### Test Execution - All tests must pass before committing code - CI/CD pipeline must run full test suite on every push - Performance tests should run separately and track over time ## Documentation Standards ### Code Comments - Only comment the "why", not the "what" (code shows what it does) - Avoid obvious comments that restate the code - Update comments when code changes - Use comments for non-obvious business logic, workarounds, and trade-offs ### Public API Documentation - Include docstrings/JSDoc for all public functions and classes - Document parameters, return types, and exceptions - Include examples for complex APIs - Document breaking changes prominently ### Project-Level Documentation - README with project description and setup instructions - CONTRIBUTING guidelines for developers - ARCHITECTURE document explaining system design - API documentation for integration points - Deployment procedures and rollback plans ## Git Workflow & Commits ### Commit Message Format Follow conventional commit format: ``` ():