Development Practices & Agent Operating Rules

This document defines how the agent should plan, implement, and document technical work.
It ensures correctness, prevents hallucinations, and establishes a consistent workflow.

1. Third-Party Package Usage

When interacting with external libraries, the agent must never guess API signatures or usage patterns.

Rules

• If fully confident about a package (e.g., TypeScript, Zod), you may proceed directly.
• If uncertain:
  1. Identify the correct library name
  2. Retrieve up-to-date documentation from an authoritative source
  3. Base all code on the retrieved documentation
• Avoid hallucinations and undocumented APIs.
• Prefer accuracy and safety over speed.

2. Task Planning Workflow

Before writing any code, you must present a plan and wait for explicit approval.

Workflow

When the user requests implementation or says “Start Task”:

1. Read the task requirements.
2. Create a concise implementation outline:
   • Key technical steps
   • Architecture choices
   • Dependencies
   • Potential challenges
   • Order of execution
3. Present the outline to the user.
4. Ask: “Do you approve this plan?”
5. Do not proceed until the user replies “yes.”

3. Implementation Philosophy

Implementations must be Safe, Sound, and Simple.

Principles

• Safe – follow stable, established patterns; validate where needed.
• Sound – technically correct, maintainable, aligned with best practices.
• Simple – avoid overengineering; implement only what’s required.

Guidelines

• Prefer clarity over cleverness.
• Avoid speculative abstractions.
• Keep solutions readable and maintainable.
• Build only what is explicitly needed.

4. Task Implementation Documentation

Every major task must produce a task log that documents what was done and why.

Task Log Contents

Each task log must include:

1. What was implemented
2. Subtasks completed
3. Why decisions were made
4. Requirements addressed
5. Code changes and rationale
6. Challenges, assumptions, considerations

Purpose

• Makes reasoning traceable
• Aids debugging
• Documents decisions for future contributors
• Provides continuity across tasks

5. Task Log Template

# Task {number}: {Title}

## What Was Implemented
- Summary of key features and behaviours

### Subtasks Completed
- {number}.{subtask} …
- {number}.{subtask} …

## Why These Decisions
Explain design choices, trade-offs, and reasoning.

## Requirements Addressed
- Requirement: …

## Code Changes
- `path/to/file` – explanation
- `path/to/file` – explanation

## Challenges & Considerations
- Edge cases
- Assumptions
- Constraints