Coding With AI

The Kōtuku repository is setup for agentic coding, and is readily configured for Claude Code and Codex by default. You'll find that an AGENTS.md file and a .claude settings folder are preconfigured for you. If you're using another agent, check if it supports AGENTS.md files, otherwise find a way to use it as the basis for your chat sessions.

If you're coding with the origo executable to write Tiri scripts exclusively, note that you'll need to install Kōtuku's GitHub repository in order to get the agent to write Tiri code. This is because the release archives are intended for running code only, and are missing the documentation and configuration information that the agent will need to be effective.

General Coding Tips

• Read the AGENTS.md file before you start. It defines the guard rails that the agent will operate under, and how it will go about building and testing its work.
• Always clear the context after completing the work on one feature and before working on another. If the context window gets to the point where it has to compact, performance of the agent can deteriorate noticeably.
• For Tiri coding, agents will write their best code after reading the existing example scripts and documentation in the repo. Although already stated in the AGENTS.md file, these directives can be ignored and you may have to give it a reminder.
• Agents will make mistakes. Enforce testing and code reviews as an essential part of the process. This will create a feedback loop between what the agent has written and what it expects as a result. You are also the last arbiter of correctness, and stepping in to make adjustments is a normal part of the process.
• As of October 2025 our best results have been observed when using Codex, however we use both Claude Code and Codex interchangeably. Avoid relying on only one agent; learning the strengths and weaknesses of multiple agents is key to unlocking higher productivity.

Skills

The repository ships a set of reusable skills in the .agents/skills/ folder, which are specially adapted for work on this project.

In Claude Code, a skill can be invoked directly as a slash command (e.g. /flute-testing), and the agent will also reach for the relevant skill automatically when a task matches its description. Codex can directly invoke skills with the $ prefix.

Tiri scripting and testing

• tiri-programming — Use before writing, editing, reviewing, or testing any Tiri code, .tiri files, scripts/gui modules, examples, or Tiri-facing APIs.
• flute-testing — Use when writing, running, extending, or planning coverage for Flute tests, including creating test_*.tiri files, adding flute_test() CMake registrations, and debugging Flute failures.

Code review and quality

• code-quality-reviewer — Reviews code changes for correctness, maintainability, compile risk, and the project's strict coding standards. Use after implementing or modifying code and before committing.
• bug-sweep <sub-project-name> — Scans a module or sub-project for bugs using parallel agents and compiles a prioritised report.
• code-cleanup-auditor <module-or-file-path> — Audits C++ modules and their TDL/CMake integration for maintainability cleanups: dead functions, stale helpers, duplicated patterns, and structural anti-patterns. This is for cleanup, not primary bug hunting.

Documentation

• doc-enhancer — Improves, rewrites, or reviews technical documentation, including the embedded C++ API sections, and markdown guides.
• doc-reviewer — Reviews documentation for developer usability, clarity, completeness, and technical accuracy, ensuring a developer can implement functionality without reverse-engineering the source.

Workflow

• commit — Commits to the repository using the project's required commit message format.

When you start a task that one of these skills covers, mentioning the skill by name (or letting the agent auto-select it) ensures the project's conventions are applied consistently.

Effective Prompting for Kōtuku

When starting a new task, you may need to explicitly remind the agent about Kōtuku-specific requirements:

For any coding task:

• "Build and test after making C++ changes" - Use if the agent is skipping compilation verification.

When asking for Tiri code:

• "Read at least 3 examples from examples/ or src/[module]/tests/ before writing code" - This will improve code quality. The Tiri skill automatically does this for you.
• Point the agent to specific example files most relevant to your task (e.g., examples/widgets.tiri for GUI work).

When asking for tests:

• "Write a Flute test following patterns in src/[module]/tests/" - Agents should study existing tests first.

When working with existing code:

• "Search for similar implementations before writing new code" - Critical for leveraging existing patterns.
• "Check the documentation in docs/xml/modules/classes/ for the [ClassName] API" - For detailed class information.

Using Multiple Agents Effectively

Different agents have different strengths. Consider these strategies:

When to switch agents:

• If one agent repeatedly makes the same mistake despite corrections.
• When you need a fresh perspective on a difficult problem.
• If the context has grown too large, ask it to save a status report for the next agent and then continue afresh.

Learning agent personalities:

• Try different agents on similar small tasks to understand their strengths.
• Some agents better understand existing code patterns.
• Some are better at generating boilerplate or test code.
• Some handle complex refactoring more reliably.

Maintaining consistency:

• When switching agents mid-feature, have the new agent review what's already been done.
• Always point new agents to AGENTS.md and relevant examples.
• Keep notes on which agent approaches worked well for different task types.

Leveraging complementary strengths:

• Use one agent for initial implementation, another for review and refinement.
• Have one agent write tests for another agent's code.
• For critical code, give multiple agents the same task and pick the best solution, or combination of both.