Toju/agents-docs/features/feature-template.md

[Feature Name]

Area: [area-name] Status: Active | In Progress | Deprecated Last updated: YYYY-MM-DD

Overview

One paragraph describing what this feature does and why it exists.

Responsibilities

• What this feature is responsible for
• Its boundaries — what it does NOT own

Key concepts

• ConceptA: short definition
• ConceptB: short definition

---

API Endpoint

Endpoint Details

• Method: [GET | POST | PUT | PATCH | DELETE]
• Path: /api/v1/[feature-path]
• Authentication: [Required | Optional | None]
• Rate Limiting: [Yes — describe | No]

Request Schema

{
  "field": "type — description"
}

Required fields:

• field (type, constraints): description

Optional fields:

• field (type): description. Defaults to "X" if not provided.

Response Schema

{
  "field": "type — description"
}

Error Responses

• 400 Bad Request: [specific causes]
• 401 Unauthorized: missing or invalid authentication
• 404 Not Found: [when this applies]
• 500 Internal Server Error: [specific causes]

---

Business Logic

Core Functionality

1. Step 1: description
2. Step 2: description
3. Step 3: description

Business Rules

• Rule 1
• Rule 2

Data Flow

Input → Validation → [Processing Steps] → Response

Dependencies

• Service/Library: what it's used for
• External API: what it's used for
• Database: what tables/collections are involved

---

Technical Implementation

Service Layer

• Location: path/to/service
• Key methods: methodName() — description

Controller / Handler

• Location: path/to/handler
• Responsibilities: request validation, service invocation, response formatting

Repository / Data Access

• Location: path/to/repository
• Tables/Collections: list the relevant database objects
• Migrations: reference the migration that created/modified the schema

Key Types

• TypeName: description of what it represents

---

Configuration

Environment Variables

• VAR_NAME: description (required | optional, default: X)

Feature Flags

• [List any feature flags, or "None"]

---

Testing

Unit Tests

• Location: path/to/tests
• Key scenarios: list the most important test cases

Integration Tests

• Location: path/to/integration/tests
• Setup: describe any required infrastructure (database, external services, etc.)
• Mocking: what external services are mocked and how

---

Error Handling & Edge Cases

Common Errors

• Error scenario: how it's handled

Edge Cases

• Edge case: expected behavior

---

Security Considerations

• Authentication requirements
• Authorization / access control
• Input validation and sanitization
• Data privacy considerations

---

Performance Considerations

• Expected response times
• Known bottlenecks
• Caching strategy (if any)

---

Known Issues and Limitations

1. Limitation: description

---

Related Features

• [Related Feature]: brief description of relationship

Changelog

Date	Change
YYYY-MM-DD	Initial documentation