@agents-inc/cli 0.32.1

package/dist/src/agents/developer/api-developer/output-format.md

@@ -0,0 +1,359 @@
+## Output Format
+
+<output_format>
+Provide your implementation in this structure:
+
+<summary>
+**Task:** [Brief description of what was implemented]
+**Status:** [Complete | Partial | Blocked]
+**Files Changed:** [count] files ([+additions] / [-deletions] lines)
+</summary>
+
+<investigation>
+**Files Examined:**
+
+| File            | Lines | What Was Learned             |
+| --------------- | ----- | ---------------------------- |
+| [/path/to/file] | [X-Y] | [Pattern/utility discovered] |
+
+**Patterns Identified:**
+
+- **Route structure:** [How routes are organized - from /path:lines]
+- **Validation approach:** [How input is validated - from /path:lines]
+- **Error handling:** [How errors are managed - from /path:lines]
+- **Database access:** [Query patterns used - from /path:lines]
+
+**Existing Code Reused:**
+
+- [Utility/middleware] from [/path] - [Why reused instead of creating new]
+  </investigation>
+
+<approach>
+**Summary:** [1-2 sentences describing the implementation approach]
+
+**Files:**
+
+| File            | Action             | Purpose               |
+| --------------- | ------------------ | --------------------- |
+| [/path/to/file] | [created/modified] | [What change and why] |
+
+**Key Decisions:**
+
+- [Decision]: [Rationale based on existing patterns from /path:lines]
+  </approach>
+
+<implementation>
+
+### [filename.ts]
+
+**Location:** `/absolute/path/to/file.ts`
+**Changes:** [Brief description - e.g., "New route handler" or "Added validation"]
+
+```typescript
+// [Description of this code block]
+[Your implementation code]
+```
+
+**Design Notes:**
+
+- [Why this approach was chosen]
+- [How it matches existing patterns]
+
+### [filename2.ts]
+
+[Same structure...]
+
+</implementation>
+
+<api_changes>
+
+## Endpoints Added/Modified
+
+### [METHOD] [/api/path]
+
+**Handler:** `/path/to/route.ts:lines`
+**Auth Required:** [Yes - middleware name / No]
+
+**Request:**
+
+```typescript
+// Path params / Query params / Body schema
+{
+  // Schema definition or description
+}
+```
+
+**Success Response:** [status code]
+
+```typescript
+{
+  // Response shape
+}
+```
+
+**Error Responses:**
+
+| Status | Condition          | Response Shape                       |
+| ------ | ------------------ | ------------------------------------ |
+| 400    | Validation failed  | `{ error: string, details?: [...] }` |
+| 401    | Not authenticated  | `{ error: string }`                  |
+| 403    | Not authorized     | `{ error: string }`                  |
+| 404    | Resource not found | `{ error: string }`                  |
+| 500    | Server error       | `{ error: string }`                  |
+
+</api_changes>
+
+<database_changes>
+
+## Schema Changes (if applicable)
+
+### Table: [table_name]
+
+**File:** `/path/to/schema.ts:lines`
+
+**Columns Added/Modified:**
+
+| Column | Type   | Constraints                       | Purpose      |
+| ------ | ------ | --------------------------------- | ------------ |
+| [name] | [type] | [nullable, default, unique, etc.] | [Why needed] |
+
+**Relationships:**
+
+- [one-to-many / many-to-many] with [other_table] via [foreign key]
+
+**Indexes:**
+
+- [Index on columns] for [query optimization reason]
+
+## Migrations (if applicable)
+
+**File:** `/path/to/migration.sql`
+**Reversible:** [Yes / No - why not]
+
+```sql
+-- Migration SQL
+```
+
+</database_changes>
+
+<security>
+
+## Security Verification
+
+**Input Validation:**
+
+- [ ] All user inputs validated before use
+- [ ] SQL injection prevented (parameterized queries / ORM)
+- [ ] Path traversal prevented (if file operations)
+- [ ] Request size limits enforced
+
+**Authentication/Authorization:**
+
+- [ ] Auth middleware applied to protected routes
+- [ ] Permission/role checks where needed
+- [ ] Resource ownership verified (user can only access their data)
+
+**Sensitive Data:**
+
+- [ ] No secrets hardcoded (using env vars)
+- [ ] No PII in logs
+- [ ] Sensitive fields excluded from API responses
+- [ ] Passwords hashed (if auth-related)
+
+**Rate Limiting:**
+
+- [ ] Rate limiting applied (if public endpoint)
+- [ ] Abuse vectors considered
+
+**Notes:**
+
+- [Any security decisions or considerations]
+
+</security>
+
+<error_handling>
+
+## Error Handling
+
+**Pattern Used:** [Matches pattern from /path:lines]
+
+**Errors Handled:**
+
+| Error Type     | HTTP Status | Handling                  | Logged? |
+| -------------- | ----------- | ------------------------- | ------- |
+| Validation     | 400         | Return validation details | No      |
+| Auth           | 401/403     | Return generic message    | Yes     |
+| Not Found      | 404         | Return not found message  | No      |
+| Business Logic | 400/422     | Return specific error     | Depends |
+| Database       | 500         | Log + generic message     | Yes     |
+| Unknown        | 500         | Log + generic message     | Yes     |
+
+**Logging:**
+
+- Errors logged with: [correlation ID, user ID, request path, etc.]
+- Log level: [error / warn depending on type]
+
+</error_handling>
+
+<tests>
+
+### [filename.test.ts]
+
+**Location:** `/absolute/path/to/file.test.ts`
+
+```typescript
+[Test code covering the implementation]
+```
+
+**Coverage:**
+
+- [x] Happy path: [scenario]
+- [x] Validation errors: [scenarios]
+- [x] Auth errors: [scenarios]
+- [x] Edge cases: [scenarios]
+
+**Test Commands:**
+
+```bash
+# Run tests for this feature
+[specific test command]
+```
+
+</tests>
+
+<verification>
+
+## Success Criteria
+
+| Criterion            | Status    | Evidence                                       |
+| -------------------- | --------- | ---------------------------------------------- |
+| [From specification] | PASS/FAIL | [How verified - test name, curl command, etc.] |
+
+## Universal Quality Checks
+
+**API Design:**
+
+- [ ] RESTful conventions followed (or GraphQL if applicable)
+- [ ] Consistent response format across endpoints
+- [ ] Appropriate HTTP status codes used
+- [ ] API versioning considered (if breaking change)
+
+**Database:**
+
+- [ ] Queries optimized (no N+1, proper indexes)
+- [ ] Transactions used for multi-step operations
+- [ ] Soft delete checks where applicable
+- [ ] Connection pooling respected
+
+**Code Quality:**
+
+- [ ] No magic numbers (named constants used)
+- [ ] No `any` types without justification
+- [ ] Follows existing naming conventions
+- [ ] Follows existing file/folder structure
+- [ ] No hardcoded config values (uses env/config)
+
+**Observability:**
+
+- [ ] Appropriate logging added
+- [ ] Errors include context for debugging
+- [ ] Metrics/tracing hooks (if applicable)
+
+## Build & Test Status
+
+- [ ] Existing tests pass
+- [ ] New tests pass (if added)
+- [ ] Build succeeds
+- [ ] No type errors
+- [ ] No lint errors
+- [ ] Migrations run successfully (if applicable)
+
+</verification>
+
+<notes>
+
+## For Reviewer
+
+- [Areas to focus review on - e.g., "The permission check logic"]
+- [Decisions that may need discussion]
+- [Alternative approaches considered and why rejected]
+
+## Scope Control
+
+**Added only what was specified:**
+
+- [Feature implemented as requested]
+
+**Did NOT add:**
+
+- [Unrequested feature avoided - why it was tempting but wrong]
+
+## Known Limitations
+
+- [Any scope reductions from spec]
+- [Technical debt incurred and why]
+- [Performance considerations for high load]
+
+## Dependencies
+
+- [New packages added: none / list with justification]
+- [Breaking changes: none / description]
+- [Migration required: yes/no]
+
+</notes>
+
+</output_format>
+
+---
+
+## Section Guidelines
+
+### When to Include Each Section
+
+| Section              | When Required                     |
+| -------------------- | --------------------------------- |
+| `<summary>`          | Always                            |
+| `<investigation>`    | Always - proves research was done |
+| `<approach>`         | Always - shows planning           |
+| `<implementation>`   | Always - the actual code          |
+| `<api_changes>`      | When API endpoints added/modified |
+| `<database_changes>` | When schema/migrations added      |
+| `<security>`         | Always for backend work           |
+| `<error_handling>`   | Always - shows error strategy     |
+| `<tests>`            | When tests are part of the task   |
+| `<verification>`     | Always - proves completion        |
+| `<notes>`            | When there's context for reviewer |
+
+### Security Checks (Framework-Agnostic)
+
+These apply regardless of framework:
+
+- **Input validation:** Never trust user input - validate everything
+- **SQL injection:** Use parameterized queries or ORM, never string concatenation
+- **Auth checks:** Verify identity AND authorization on every protected route
+- **Secrets:** Environment variables only, never in code
+- **Logging:** Never log passwords, tokens, or PII
+
+### Database Checks (ORM-Agnostic)
+
+- **Transactions:** Multi-step operations must be atomic
+- **N+1 queries:** Avoid fetching related data in loops
+- **Indexes:** Add for frequently queried columns
+- **Soft delete:** Check for deleted records if pattern exists
+- **Connection handling:** Don't leak connections
+
+### Error Handling (Framework-Agnostic)
+
+Every error needs:
+
+1. **Appropriate status code:** 4xx for client errors, 5xx for server
+2. **Safe message:** Don't expose internals to clients
+3. **Logging:** Log enough to debug, not too much PII
+4. **Consistency:** Same error format across all endpoints
+
+### API Design (Framework-Agnostic)
+
+- **Idempotency:** PUT/DELETE should be idempotent
+- **Pagination:** List endpoints should paginate
+- **Filtering:** Support common filter patterns
+- **Versioning:** Consider when making breaking changes