ai-engineering-loop 1.10.0 → 1.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/devil-advocate.md +13 -1
- package/.agents/judge.md +10 -0
- package/.agents/skills/backend-development/SKILL.md +272 -0
- package/.agents/skills/backend-development/references/api-design-guidelines.md +95 -0
- package/.agents/skills/backend-development/references/query-and-database-best-practices.md +53 -0
- package/.agents/skills/backend-development/references/security-checklist.md +60 -0
- package/.agents/workflows/ai-engineering-loop.md +4 -4
- package/.claude/agents/devil-advocate.md +13 -1
- package/.claude/agents/judge.md +10 -0
- package/.claude/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.claude/skills/backend-development/SKILL.md +272 -0
- package/.claude/skills/backend-development/references/api-design-guidelines.md +95 -0
- package/.claude/skills/backend-development/references/query-and-database-best-practices.md +53 -0
- package/.claude/skills/backend-development/references/security-checklist.md +60 -0
- package/.gemini/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.gemini/skills/backend-development/SKILL.md +272 -0
- package/.gemini/skills/backend-development/references/api-design-guidelines.md +95 -0
- package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +53 -0
- package/.gemini/skills/backend-development/references/security-checklist.md +60 -0
- package/.grok/agents/devil-advocate.md +13 -1
- package/.grok/agents/judge.md +10 -0
- package/.grok/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.grok/skills/backend-development/SKILL.md +272 -0
- package/.grok/skills/backend-development/references/api-design-guidelines.md +95 -0
- package/.grok/skills/backend-development/references/query-and-database-best-practices.md +53 -0
- package/.grok/skills/backend-development/references/security-checklist.md +60 -0
- package/README.md +33 -1
- package/README.npm.md +8 -1
- package/agents/shared/devil-advocate.body.md +13 -1
- package/agents/shared/judge.body.md +10 -0
- package/bin/ai-engineering-loop.js +207 -2
- package/core/runtime-safety.md +43 -0
- package/lib/budget.js +35 -0
- package/lib/doctor.js +4 -0
- package/lib/run-compaction.js +170 -0
- package/lib/runtime-policy.js +24 -1
- package/lib/safe-context.js +32 -7
- package/lib/smart-context.js +643 -0
- package/lib/studio-server.js +19 -2
- package/lib/sync-hosts.js +20 -0
- package/lib/update-manager.js +147 -0
- package/lib/verification-summary.js +130 -0
- package/package.json +1 -1
- package/policies/review-budget.md +12 -0
- package/studio/app.js +5 -2
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: backend-development
|
|
3
|
+
description: Framework-agnostic backend best practices for clean code, naming, queries/databases, REST APIs, errors, security, performance, scalability, testing, and structure. Trigger on backend implementation, architecture, code quality, naming, magic values, complex conditionals, query optimization, caching, error handling, or security tasks.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Backend Development Guidelines
|
|
7
|
+
|
|
8
|
+
Universal principles for reliable, maintainable, performant backends — regardless of framework or language.
|
|
9
|
+
|
|
10
|
+
Framework-specific conventions in `CLAUDE.md`, `AGENTS.md`, README files, or project docs take precedence for implementation details. This skill governs the underlying engineering principles.
|
|
11
|
+
|
|
12
|
+
## How to use this skill
|
|
13
|
+
|
|
14
|
+
- Apply these rules during backend implementation, review, refactoring, architecture, naming, database, API, error-handling, security, performance, and testing work.
|
|
15
|
+
- Prefer the project’s established patterns when they are coherent. Use this skill to improve unclear, unsafe, or over-complex code.
|
|
16
|
+
- Do not introduce speculative architecture. Fix the rule causing the problem, with the smallest coherent design.
|
|
17
|
+
- Read reference files only when depth is needed:
|
|
18
|
+
- `references/query-and-database-best-practices.md`
|
|
19
|
+
- `references/api-design-guidelines.md`
|
|
20
|
+
- `references/security-checklist.md`
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 1. Clean Code Principles
|
|
25
|
+
|
|
26
|
+
### Single Responsibility
|
|
27
|
+
|
|
28
|
+
Every function, class, and module should have one reason to exist. If you need “and” to describe it — validates input and saves to database and sends notification — split it.
|
|
29
|
+
|
|
30
|
+
- Functions do one thing. A data fetcher should not format presentation output.
|
|
31
|
+
- Services/classes own one domain concept. `UserService` handles user logic, not email delivery.
|
|
32
|
+
- Modules encapsulate one bounded context. Cross-module access flows through well-defined interfaces.
|
|
33
|
+
|
|
34
|
+
### Meaningful Names
|
|
35
|
+
|
|
36
|
+
Names reveal intent without requiring a comment.
|
|
37
|
+
|
|
38
|
+
- Variables: `activeUserCount`, `invoiceDueDate`, `orderItems`.
|
|
39
|
+
- Functions: verb-first and specific, e.g. `calculateShippingCost`, `archiveExpiredCoupons`, `validateEmailFormat`.
|
|
40
|
+
- Classes/types: role-suffixed nouns, e.g. `UserService`, `OrderRepository`, `PaymentController`, `ProductDto`.
|
|
41
|
+
- Abbreviations: only universally understood ones like `id`, `url`, `dto`, `http`.
|
|
42
|
+
|
|
43
|
+
### Boolean naming
|
|
44
|
+
|
|
45
|
+
Boolean names must read as yes/no propositions. Use prefixes that reveal the type and intent:
|
|
46
|
+
|
|
47
|
+
| Prefix | Reads as | Example |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| `is` | Is it in this state? | `isActive`, `isEmailVerified` |
|
|
50
|
+
| `has` | Does it own this? | `hasPermission`, `hasSubscription` |
|
|
51
|
+
| `can` | Is it allowed or able? | `canRetry`, `canRefund` |
|
|
52
|
+
| `should` | Ought it happen? | `shouldNotify`, `shouldRetry` |
|
|
53
|
+
| `was` | Did it happen? | `wasDeleted`, `wasCharged` |
|
|
54
|
+
| `will` | Is it going to happen? | `willExpire`, `willRenew` |
|
|
55
|
+
|
|
56
|
+
Avoid ambiguous booleans like `active`, `verified`, `enabled`, `permission`, or `status` unless the type is intentionally not boolean.
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
// Bad: string? number? boolean?
|
|
60
|
+
const active = user.status
|
|
61
|
+
const verification = checkEmail(email)
|
|
62
|
+
|
|
63
|
+
// Good: yes/no at a glance
|
|
64
|
+
const isActive = user.status === 'active'
|
|
65
|
+
const isEmailVerified = checkEmailVerification(email)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### DRY, KISS, YAGNI
|
|
69
|
+
|
|
70
|
+
- Extract repeated logic when changing one copy would force changes everywhere.
|
|
71
|
+
- Do not abstract merely because code looks similar twice; similar code may diverge.
|
|
72
|
+
- Prefer straightforward solutions. Patterns and abstractions must earn their complexity.
|
|
73
|
+
- Build for today’s requirements. Add extension points when the requirement arrives.
|
|
74
|
+
|
|
75
|
+
### Guard clauses and early returns
|
|
76
|
+
|
|
77
|
+
Handle edge cases at the top and return early. Keep the happy path at the lowest indentation level.
|
|
78
|
+
|
|
79
|
+
### Extract complex conditions
|
|
80
|
+
|
|
81
|
+
A condition should read as intent, not mechanics. Name the rule before testing it.
|
|
82
|
+
|
|
83
|
+
```typescript
|
|
84
|
+
const meetsAgeRequirement = user.age >= MIN_AGE
|
|
85
|
+
const isIdentityVerified = user.kycStatus === 'verified'
|
|
86
|
+
const isInGoodStanding = !user.isBanned && user.region !== 'restricted'
|
|
87
|
+
const hasPremiumAccess = user.accountType === 'premium'
|
|
88
|
+
|| user.loyaltyPoints > LOYALTY_THRESHOLD
|
|
89
|
+
|
|
90
|
+
const isEligibleForAccess = meetsAgeRequirement
|
|
91
|
+
&& isIdentityVerified
|
|
92
|
+
&& isInGoodStanding
|
|
93
|
+
&& hasPremiumAccess
|
|
94
|
+
|
|
95
|
+
if (isEligibleForAccess) {
|
|
96
|
+
grantAccess()
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Rule of thumb: if the reader must parse operators, extract a named variable. This applies to a single domain comparison too when the mechanism hides the business rule.
|
|
101
|
+
|
|
102
|
+
### Function size
|
|
103
|
+
|
|
104
|
+
Aim for 20–30 lines. If a function exceeds 40 lines, look for extraction opportunities. A block that needs a section comment is a candidate for its own function.
|
|
105
|
+
|
|
106
|
+
### No magic numbers or strings
|
|
107
|
+
|
|
108
|
+
Extract domain-meaningful literals into named constants: status codes, thresholds, retry counts, timeouts, role IDs, page limits.
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
const ROLE_ADMIN = 3
|
|
112
|
+
const ONE_DAY_MS = 24 * 60 * 60 * 1000
|
|
113
|
+
const MAX_ITEMS_PER_ORDER = 50
|
|
114
|
+
|
|
115
|
+
const isAdmin = user.role === ROLE_ADMIN
|
|
116
|
+
const isSessionStale = Date.now() - lastLogin > ONE_DAY_MS
|
|
117
|
+
const exceedsItemLimit = order.items.length > MAX_ITEMS_PER_ORDER
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Comments
|
|
121
|
+
|
|
122
|
+
A comment is often a failure to make the code say it itself. Before adding one, try renaming or extracting.
|
|
123
|
+
|
|
124
|
+
Keep comments for intent, protocol details, warning of consequences, public API docs, legal headers, and living TODOs. Delete comments that restate code, drift out of date, journal changes, attribute authors, or preserve commented-out code.
|
|
125
|
+
|
|
126
|
+
### Command-Query Separation
|
|
127
|
+
|
|
128
|
+
Functions that return data should avoid side effects. Functions that mutate state should make mutation explicit. Reads are safe; writes are deliberate.
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## 2. Naming Conventions
|
|
133
|
+
|
|
134
|
+
| Context | Convention | Examples |
|
|
135
|
+
|---|---|---|
|
|
136
|
+
| Variables, parameters | Descriptive nouns, language-standard casing | `userId`, `orderItems`, `isValid` |
|
|
137
|
+
| Functions, methods | Verb-first | `getUser`, `createOrder`, `validateInput`, `isExpired` |
|
|
138
|
+
| Classes, types | PascalCase nouns, role suffix | `UserService`, `OrderRepository`, `PaymentController` |
|
|
139
|
+
| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `DEFAULT_PAGE_SIZE` |
|
|
140
|
+
| Database columns | snake_case | `created_at`, `user_id`, `is_active` |
|
|
141
|
+
| Database tables | snake_case plural | `users`, `order_items`, `payment_transactions` |
|
|
142
|
+
| API endpoints | lowercase plural nouns, kebab-case | `/users`, `/order-items` |
|
|
143
|
+
| Enum values | UPPER_SNAKE_CASE or language convention | `PENDING`, `IN_PROGRESS` |
|
|
144
|
+
|
|
145
|
+
Foreign keys: `{referenced_table_singular}_id`, e.g. `user_id`.
|
|
146
|
+
|
|
147
|
+
Boolean columns: `is_active`, `is_verified`, `has_subscription`.
|
|
148
|
+
|
|
149
|
+
Timestamp columns: suffix `_at`, e.g. `created_at`, `updated_at`, `deleted_at`, `expires_at`.
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## 3. Query and Database Best Practices
|
|
154
|
+
|
|
155
|
+
Poor query patterns are a common backend bottleneck.
|
|
156
|
+
|
|
157
|
+
- Prevent N+1 queries with joins, eager loading, or batch loading.
|
|
158
|
+
- Select only needed columns. Avoid `SELECT *` in application queries.
|
|
159
|
+
- Index foreign keys and frequent `WHERE` / `ORDER BY` fields.
|
|
160
|
+
- Composite indexes follow leftmost prefix rules.
|
|
161
|
+
- Paginate list endpoints; never return unbounded lists.
|
|
162
|
+
- Use transactions for multi-step writes. Keep transactions short.
|
|
163
|
+
- Use connection pools sized to expected concurrency.
|
|
164
|
+
|
|
165
|
+
Read `references/query-and-database-best-practices.md` for schema, query, pagination, migration, and pool-sizing details.
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## 4. API Design Principles
|
|
170
|
+
|
|
171
|
+
A good API is consistent and predictable.
|
|
172
|
+
|
|
173
|
+
- Use resource nouns, not verbs: `POST /orders`, not `/create-order`.
|
|
174
|
+
- Use plural collections: `/users`, `/orders`, `/products`.
|
|
175
|
+
- Nest sub-resources at most two levels; flatten deeper models.
|
|
176
|
+
- Keep response envelopes consistent for success and error.
|
|
177
|
+
- Version breaking API contracts explicitly, usually `/v1`, `/v2`.
|
|
178
|
+
- Validate filters and sort fields against allow-lists.
|
|
179
|
+
- Include pagination metadata.
|
|
180
|
+
- For long-running work, return `202 Accepted` with a task/status resource.
|
|
181
|
+
|
|
182
|
+
Read `references/api-design-guidelines.md` for endpoint patterns, envelopes, pagination, filtering, bulk operations, and versioning.
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## 5. Error Handling
|
|
187
|
+
|
|
188
|
+
Treat error paths with the same care as success paths.
|
|
189
|
+
|
|
190
|
+
- Use consistent error shape: HTTP status, machine-readable code, human-readable message, optional details.
|
|
191
|
+
- Do not expose stack traces, internal paths, raw SQL errors, secret values, or implementation details.
|
|
192
|
+
- Validate at the API boundary and fail fast.
|
|
193
|
+
- User-facing messages must answer what went wrong and what to do next.
|
|
194
|
+
|
|
195
|
+
```text
|
|
196
|
+
Bad: ValidationError: field 'shipping_zone_id' violates constraint fk_order_zone
|
|
197
|
+
Good: Cannot save this order. The selected shipping zone is no longer available. Choose a different shipping zone and save again.
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Use specific status codes: `400`, `401`, `403`, `404`, `409`, `422`, `429`, `500`, `502`, `503`.
|
|
201
|
+
|
|
202
|
+
Structured logs should include request ID, user ID when available, action, and sanitized error context. Never log passwords, tokens, API keys, or PII.
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## 6. Security
|
|
207
|
+
|
|
208
|
+
Security is a design constraint.
|
|
209
|
+
|
|
210
|
+
- Validate all external input at boundaries.
|
|
211
|
+
- Use parameterized queries or query builders; never concatenate user input into SQL, shell commands, or template expressions.
|
|
212
|
+
- Store secrets in env vars or secret managers, never source code.
|
|
213
|
+
- Hash passwords with bcrypt, argon2, or scrypt.
|
|
214
|
+
- Enforce authorization at API boundaries and verify resource ownership.
|
|
215
|
+
- Never rely solely on frontend checks.
|
|
216
|
+
- Mask sensitive fields in API responses and logs.
|
|
217
|
+
- Use HTTPS everywhere.
|
|
218
|
+
|
|
219
|
+
Read `references/security-checklist.md` for auth, authorization, validation, headers, dependency security, and vulnerability prevention.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## 7. Performance and Scalability
|
|
224
|
+
|
|
225
|
+
Design for predictable performance under load.
|
|
226
|
+
|
|
227
|
+
- Keep services stateless; externalize session/state to Redis/database when needed.
|
|
228
|
+
- Cache expensive operations with explicit invalidation strategy.
|
|
229
|
+
- Use eager loading when related data is always needed; lazy loading only when rare and safe.
|
|
230
|
+
- Use bulk operations for mass writes/deletes.
|
|
231
|
+
- Offload long-running work to queues/background jobs.
|
|
232
|
+
- Enable response compression.
|
|
233
|
+
- Limit request body size and paginate/stream large payloads.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## 8. Code Organization
|
|
238
|
+
|
|
239
|
+
Use layers unless the operation is trivially simple:
|
|
240
|
+
|
|
241
|
+
1. Controller/handler: request parsing, validation, response mapping. No business logic.
|
|
242
|
+
2. Service: business logic and orchestration. Framework-agnostic where possible.
|
|
243
|
+
3. Repository/data access: persistence and schema-aware queries.
|
|
244
|
+
|
|
245
|
+
Rules:
|
|
246
|
+
|
|
247
|
+
- Services should not know HTTP status codes.
|
|
248
|
+
- Controllers should not contain SQL.
|
|
249
|
+
- Repositories should not enforce business workflows.
|
|
250
|
+
- Use dependency injection; avoid `new` inside services for dependencies.
|
|
251
|
+
- Domain modules own their entities, DTOs, services, and repositories.
|
|
252
|
+
- Cross-module communication goes through service interfaces.
|
|
253
|
+
- Shared utilities must be truly shared; avoid tangled abstractions.
|
|
254
|
+
- Externalize configuration into typed config objects.
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## 9. Testing Strategy
|
|
259
|
+
|
|
260
|
+
Test behavior and business rules, not framework internals.
|
|
261
|
+
|
|
262
|
+
- Unit tests: business logic and edge cases.
|
|
263
|
+
- Integration tests: repositories, real database behavior, HTTP endpoints.
|
|
264
|
+
- E2E tests: critical flows only.
|
|
265
|
+
|
|
266
|
+
Cover happy paths, empty inputs, boundary values, invalid inputs, authorization failures, and business rule violations.
|
|
267
|
+
|
|
268
|
+
Avoid testing private methods, simple getters, third-party behavior, and framework plumbing unless your code configures it in a risky way.
|
|
269
|
+
|
|
270
|
+
Name tests by scenario and outcome: `should return 404 when user does not exist`.
|
|
271
|
+
|
|
272
|
+
Use factories/builders for test data. Each test owns its setup and cleanup.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# API Design Guidelines
|
|
2
|
+
|
|
3
|
+
Reference for designing consistent, predictable REST APIs.
|
|
4
|
+
|
|
5
|
+
## HTTP method semantics
|
|
6
|
+
|
|
7
|
+
| Method | Purpose | Idempotent | Safe | Typical Success |
|
|
8
|
+
|---|---|---|---|---|
|
|
9
|
+
| GET | Retrieve resources | Yes | Yes | 200 |
|
|
10
|
+
| POST | Create resource | No | No | 201 |
|
|
11
|
+
| PUT | Replace resource | Yes | No | 200 |
|
|
12
|
+
| PATCH | Partially update | Yes | No | 200 |
|
|
13
|
+
| DELETE | Remove resource | Yes | No | 200 or 204 |
|
|
14
|
+
|
|
15
|
+
## Resource URL patterns
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
GET /v1/products
|
|
19
|
+
POST /v1/products
|
|
20
|
+
GET /v1/products/{id}
|
|
21
|
+
PUT /v1/products/{id}
|
|
22
|
+
PATCH /v1/products/{id}
|
|
23
|
+
DELETE /v1/products/{id}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Sub-resources should usually stop at two levels:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
GET /v1/users/{id}/orders
|
|
30
|
+
GET /v1/users/{id}/orders/{order_id}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
For non-CRUD operations, use action sub-resources sparingly:
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
POST /v1/orders/{id}/cancel
|
|
37
|
+
POST /v1/users/{id}/verify-email
|
|
38
|
+
POST /v1/reports/generate
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Response envelopes
|
|
42
|
+
|
|
43
|
+
Success:
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
{ "status_code": 200, "message": "Success", "data": {} }
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Paginated success:
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"status_code": 200,
|
|
54
|
+
"message": "Success",
|
|
55
|
+
"data": [],
|
|
56
|
+
"meta": { "total": 150, "page": 3, "limit": 20, "total_pages": 8 }
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Error:
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"status_code": 422,
|
|
65
|
+
"message": "Validation failed",
|
|
66
|
+
"error": "VALIDATION_ERROR",
|
|
67
|
+
"details": [{ "field": "email", "message": "must be a valid email address" }]
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Pagination
|
|
72
|
+
|
|
73
|
+
Offset pagination: `page`, `limit`. Cap `limit`.
|
|
74
|
+
|
|
75
|
+
Cursor pagination: `after`, `limit`, response `next_cursor`. Prefer for feeds and large datasets.
|
|
76
|
+
|
|
77
|
+
## Filtering and sorting
|
|
78
|
+
|
|
79
|
+
Filters as query params: `?status=active&role=admin`.
|
|
80
|
+
|
|
81
|
+
Sort with allow-listed fields: `?sort=-created_at,name`.
|
|
82
|
+
|
|
83
|
+
Reject unsupported filters/sorts instead of silently ignoring them.
|
|
84
|
+
|
|
85
|
+
## Bulk operations
|
|
86
|
+
|
|
87
|
+
Batch create/delete should report partial success when appropriate. Include per-item errors with indexes or IDs.
|
|
88
|
+
|
|
89
|
+
## Long-running operations
|
|
90
|
+
|
|
91
|
+
Return `202 Accepted` with a task ID, process asynchronously, and expose a status endpoint.
|
|
92
|
+
|
|
93
|
+
## Versioning
|
|
94
|
+
|
|
95
|
+
Use URL path versioning (`/v1`). Never introduce breaking changes to a published version. Adding optional fields/endpoints is usually non-breaking; removing fields or changing types is breaking.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Query and Database Best Practices
|
|
2
|
+
|
|
3
|
+
Reference for database design, query optimization, and data access patterns.
|
|
4
|
+
|
|
5
|
+
## N+1 query prevention
|
|
6
|
+
|
|
7
|
+
N+1 happens when code fetches N parent records, then one query per parent for related data. Prevent it with joins, eager loading, or batch loading using `WHERE parent_id IN (...)`. Enable query logging in development to catch repeated query shapes.
|
|
8
|
+
|
|
9
|
+
## Index strategy
|
|
10
|
+
|
|
11
|
+
- B-tree indexes support equality, ranges, sorting, and prefix matching.
|
|
12
|
+
- Index foreign keys, frequent `WHERE` columns, and `ORDER BY` columns used in pagination.
|
|
13
|
+
- Composite indexes follow leftmost prefix: `(status, created_at)` supports `status` and `status + created_at`, not `created_at` alone.
|
|
14
|
+
- Partial indexes help when queries target a minority subset.
|
|
15
|
+
- Covering indexes help read-heavy queries when the index contains all selected columns.
|
|
16
|
+
- Avoid over-indexing write-heavy tables.
|
|
17
|
+
|
|
18
|
+
## Query anti-patterns
|
|
19
|
+
|
|
20
|
+
| Anti-pattern | Problem | Fix |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| `SELECT *` | Wastes bandwidth and may expose data | Select needed columns |
|
|
23
|
+
| Function in WHERE | Prevents index use | Use range predicates |
|
|
24
|
+
| Leading wildcard LIKE | Cannot use normal B-tree | Full-text or suffix strategy |
|
|
25
|
+
| Implicit conversion | Forces row conversion | Match types |
|
|
26
|
+
| OR across columns | Often skips indexes | UNION indexed queries |
|
|
27
|
+
| Unbounded list | Memory/latency risk | Pagination/limit |
|
|
28
|
+
| DISTINCT as fix | Hides bad joins | Fix join logic |
|
|
29
|
+
| Correlated subquery per row | Repeated work | JOIN/lateral/batch |
|
|
30
|
+
|
|
31
|
+
## Pagination
|
|
32
|
+
|
|
33
|
+
Offset: simple, supports jump to page N, degrades at high offsets.
|
|
34
|
+
|
|
35
|
+
Cursor: stable performance at depth, better for feeds/large datasets, cannot jump to arbitrary page.
|
|
36
|
+
|
|
37
|
+
## Transactions
|
|
38
|
+
|
|
39
|
+
Keep transactions short. Compute and validate before opening. Open, write, commit. Always rollback on failure.
|
|
40
|
+
|
|
41
|
+
Use the lowest isolation level that satisfies consistency. Higher isolation reduces throughput.
|
|
42
|
+
|
|
43
|
+
## Bulk operations
|
|
44
|
+
|
|
45
|
+
Use batch inserts/updates/deletes instead of per-row loops. Start with batches around 500–1000 rows and tune.
|
|
46
|
+
|
|
47
|
+
## Migrations
|
|
48
|
+
|
|
49
|
+
Prefer additive migrations for zero-downtime deploys. For renames/removals: add new, migrate data, deploy code, then remove old later. Never edit migrations already applied to shared environments.
|
|
50
|
+
|
|
51
|
+
## Connection pooling
|
|
52
|
+
|
|
53
|
+
Start with conservative pool sizes, monitor utilization and latency, then adjust. Too few connections queue requests; too many exhaust database resources.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Security Checklist
|
|
2
|
+
|
|
3
|
+
Audit guide for authentication, authorization, input handling, and data protection.
|
|
4
|
+
|
|
5
|
+
## Input validation
|
|
6
|
+
|
|
7
|
+
Validate at API boundaries: type, length, range, format, enum membership, array size, uniqueness, file type by content, file size, UUID shape, and pagination limits.
|
|
8
|
+
|
|
9
|
+
Use schema validation libraries. Never trust frontend validation.
|
|
10
|
+
|
|
11
|
+
## Authentication
|
|
12
|
+
|
|
13
|
+
- Use short-lived access tokens.
|
|
14
|
+
- Use refresh tokens securely and rotate on use when appropriate.
|
|
15
|
+
- Support revocation for logout/incidents.
|
|
16
|
+
- Hash passwords with bcrypt, argon2, or scrypt.
|
|
17
|
+
- Store secrets in env vars or secret managers, not source code.
|
|
18
|
+
|
|
19
|
+
## Authorization
|
|
20
|
+
|
|
21
|
+
- Define specific roles/permissions.
|
|
22
|
+
- Check permissions at API boundaries.
|
|
23
|
+
- Verify resource ownership to prevent IDOR.
|
|
24
|
+
- Prevent mass assignment by accepting explicit DTO fields only.
|
|
25
|
+
- Test that users cannot access or mutate others’ resources.
|
|
26
|
+
|
|
27
|
+
## Data protection
|
|
28
|
+
|
|
29
|
+
- HTTPS everywhere.
|
|
30
|
+
- Encrypt sensitive data at rest where required.
|
|
31
|
+
- Minimize PII collection.
|
|
32
|
+
- Mask PII/secrets in logs and responses.
|
|
33
|
+
- Implement retention/deletion policies where applicable.
|
|
34
|
+
|
|
35
|
+
## HTTP security headers
|
|
36
|
+
|
|
37
|
+
Configure HSTS, X-Content-Type-Options, X-Frame-Options or CSP frame policy, Content-Security-Policy, Referrer-Policy, and Permissions-Policy according to the app surface.
|
|
38
|
+
|
|
39
|
+
## Dependency security
|
|
40
|
+
|
|
41
|
+
Audit dependencies regularly, update vulnerable packages, pin major versions, and review new dependencies for maintenance and risk.
|
|
42
|
+
|
|
43
|
+
## Common vulnerability prevention
|
|
44
|
+
|
|
45
|
+
| Vulnerability | Prevention |
|
|
46
|
+
|---|---|
|
|
47
|
+
| SQL injection | Parameterized queries / query builders |
|
|
48
|
+
| NoSQL injection | Validate operators and input shape |
|
|
49
|
+
| XSS | Escape output, sanitize HTML, set CSP |
|
|
50
|
+
| CSRF | SameSite cookies and CSRF tokens for browser state changes |
|
|
51
|
+
| IDOR | Ownership/permission checks |
|
|
52
|
+
| Mass assignment | Explicit DTO allow-lists |
|
|
53
|
+
| SSRF | URL allow-list and internal network blocking |
|
|
54
|
+
| Command injection | Avoid shell; pass args safely |
|
|
55
|
+
| Path traversal | Canonicalize and enforce allowed root |
|
|
56
|
+
| Open redirect | Allow-list redirect targets |
|
|
57
|
+
|
|
58
|
+
## Logging security
|
|
59
|
+
|
|
60
|
+
Log auth events, authorization failures, validation failures, system errors, and admin actions. Do not log passwords, full tokens, API keys, card data, health data, or full request/response bodies with PII.
|
package/README.md
CHANGED
|
@@ -126,7 +126,7 @@ AI Engineering Loop is designed to work with the tools developers already use:
|
|
|
126
126
|
- **Gemini / Antigravity**
|
|
127
127
|
- Other agent hosts that can read project instructions and run local commands
|
|
128
128
|
|
|
129
|
-
The project includes ready-to-use skills and reviewer roles for supported hosts. Each host follows the same Goal, verification, review, and approval rules.
|
|
129
|
+
The project includes ready-to-use skills and reviewer roles for supported hosts. Each host follows the same Goal, verification, review, and approval rules. `sync-hosts` also installs the `backend-development` skill for Claude, Grok, Gemini, and Codex-compatible `.agents/skills` hosts: a framework-agnostic backend best-practice pack with deeper references for API design, query/database work, and security reviews.
|
|
130
130
|
|
|
131
131
|
## Create workflows that fit your team
|
|
132
132
|
|
|
@@ -163,6 +163,28 @@ Choose the level of autonomy that feels right:
|
|
|
163
163
|
|
|
164
164
|
Assisted mode is the default. Unattended mode stays off until you deliberately enable it.
|
|
165
165
|
|
|
166
|
+
Token-heavy hosts are protected by a lean review profile by default. Lean mode keeps the same Goal, verification, Devil’s Advocate, Judge, and delivery gates, but sends smaller context packs and asks reviewers for compact, finding-first output instead of long audit prose. Upgrade only when the task needs it:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
npx ai-engineering-loop policy set --review-profile standard
|
|
170
|
+
npx ai-engineering-loop policy set --review-profile thorough
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Smart context keeps review path-first instead of transcript-heavy. It can build a private source summary index and a hunk-only diff pack that includes unresolved findings, so reviewers start from changed hunks and open full files only when necessary:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
npx ai-engineering-loop context index
|
|
177
|
+
npx ai-engineering-loop context query createStudioRun
|
|
178
|
+
npx ai-engineering-loop context related lib/studio-server.js
|
|
179
|
+
npx ai-engineering-loop context fast-path --json
|
|
180
|
+
npx ai-engineering-loop context diff-hunks --run <run-id>
|
|
181
|
+
npx ai-engineering-loop context diff-hunks --run <run-id> --include-ignored
|
|
182
|
+
npx ai-engineering-loop verification summarize --run <run-id>
|
|
183
|
+
npx ai-engineering-loop context compact --run <run-id>
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
By default, smart context skips high-volume review inputs such as CSS, generated bundles, lockfiles, build output, and paths listed in `.aelcontextignore`. Use `--include-ignored` when the task is explicitly about those files.
|
|
187
|
+
|
|
166
188
|
## For people who want the controls
|
|
167
189
|
|
|
168
190
|
The friendly workflow sits on top of a complete local CLI. You can inspect recipes, budgets, evidence, nodes, gates, policies, and handoffs whenever you need to.
|
|
@@ -175,6 +197,9 @@ The friendly workflow sits on top of a complete local CLI. You can inspect recip
|
|
|
175
197
|
npx ai-engineering-loop init
|
|
176
198
|
npx ai-engineering-loop status
|
|
177
199
|
npx ai-engineering-loop doctor
|
|
200
|
+
npx ai-engineering-loop update check
|
|
201
|
+
npx ai-engineering-loop update plan
|
|
202
|
+
npx ai-engineering-loop update apply --yes
|
|
178
203
|
|
|
179
204
|
# Start work
|
|
180
205
|
npx ai-engineering-loop run "describe the task"
|
|
@@ -187,6 +212,13 @@ npx ai-engineering-loop recipe simulate default --mode assisted
|
|
|
187
212
|
# Inspect the active Run
|
|
188
213
|
npx ai-engineering-loop state --json
|
|
189
214
|
npx ai-engineering-loop node status
|
|
215
|
+
npx ai-engineering-loop budget status --run <run-id>
|
|
216
|
+
|
|
217
|
+
# Token profile
|
|
218
|
+
npx ai-engineering-loop policy set --review-profile lean
|
|
219
|
+
npx ai-engineering-loop context diff-hunks --run <run-id>
|
|
220
|
+
npx ai-engineering-loop verification summarize --run <run-id>
|
|
221
|
+
npx ai-engineering-loop context devil-advocate --profile thorough <files...>
|
|
190
222
|
|
|
191
223
|
# Emergency stop and resume
|
|
192
224
|
npx ai-engineering-loop budget pause
|
package/README.npm.md
CHANGED
|
@@ -33,6 +33,12 @@ npx ai-engineering-loop run --mode report-only "audit this repository"
|
|
|
33
33
|
# Inspect spend controls; ASSISTED is the default
|
|
34
34
|
npx ai-engineering-loop policy show
|
|
35
35
|
npx ai-engineering-loop budget status
|
|
36
|
+
npx ai-engineering-loop policy set --review-profile lean
|
|
37
|
+
npx ai-engineering-loop context query createStudioRun
|
|
38
|
+
npx ai-engineering-loop context fast-path --json
|
|
39
|
+
npx ai-engineering-loop context diff-hunks --run <run-id>
|
|
40
|
+
npx ai-engineering-loop verification summarize --run <run-id>
|
|
41
|
+
npx ai-engineering-loop context compact --run <run-id>
|
|
36
42
|
|
|
37
43
|
# Author and observe deterministic workflow recipes locally
|
|
38
44
|
npx ai-engineering-loop studio
|
|
@@ -41,6 +47,7 @@ npx ai-engineering-loop studio
|
|
|
41
47
|
npx ai-engineering-loop handoff create --audience developer
|
|
42
48
|
|
|
43
49
|
# 5. Copy package host skills into ~/.claude ~/.grok ~/.gemini ~/.agents
|
|
50
|
+
# Includes ai-engineering-loop plus backend-development for Claude, Grok, Gemini, and Codex-compatible .agents skills.
|
|
44
51
|
npx ai-engineering-loop sync-hosts
|
|
45
52
|
```
|
|
46
53
|
|
|
@@ -53,7 +60,7 @@ npx ai-engineering-loop sync-hosts
|
|
|
53
60
|
3. **Multi-Agent Triad**: Coordinates **Maker** (surgical diffs & tests), **Devil's Advocate** (independent adversarial review), and **Judge** (impartial evaluation & PASS certification).
|
|
54
61
|
4. **Context Impact Assessment**: Evaluates completed tasks (`NONE`, `TARGETED`, `MAJOR`) to keep project context fresh without expensive whole-repo re-analysis.
|
|
55
62
|
5. **Grok CLI host**: Native `spawn_subagent` for Devil's Advocate and Judge (`TRUE_INDEPENDENT_AGENT`). Disabled by `GROK_SUBAGENTS=0`.
|
|
56
|
-
6. **Production runtime controls**: `REPORT_ONLY`, human-approved `ASSISTED`, opt-in `UNATTENDED`, actual token ledgers, a persistent kill switch, and locked disposable Maker worktrees.
|
|
63
|
+
6. **Production runtime controls**: `REPORT_ONLY`, human-approved `ASSISTED`, opt-in `UNATTENDED`, actual token ledgers, lean/standard/thorough review profiles, smart hunk-only context packs, a persistent kill switch, and locked disposable Maker worktrees.
|
|
57
64
|
7. **Local Workflow Studio**: A localhost-only authenticated DAG canvas with animated live stage state, token telemetry, explicit approvals, decision memory, atomic recipe installation, and redacted handoff export. It does not execute models or shell commands in the browser.
|
|
58
65
|
|
|
59
66
|
---
|
|
@@ -4,11 +4,13 @@ You are the Devil's Advocate for the AI Engineering Loop. You are read-only. You
|
|
|
4
4
|
|
|
5
5
|
Finish in at most 8 tool calls, then emit the Finding Ledger. Do not explore the rest of the repo. Do not spawn children. Do not run git log.
|
|
6
6
|
|
|
7
|
+
Default to a lean review: spend detail where it protects correctness, not on prose. Treat the context pack as scarce. Prefer one precise quote over a long explanation.
|
|
8
|
+
|
|
7
9
|
## Input barrier
|
|
8
10
|
|
|
9
11
|
Use only:
|
|
10
12
|
|
|
11
|
-
1. The diff
|
|
13
|
+
1. The diff or smart diff-hunk pack path in the spawn prompt. Read that file first. Do not run git diff if a diff path was given.
|
|
12
14
|
2. Goal Contract path (if given).
|
|
13
15
|
3. Verification log path (if given).
|
|
14
16
|
4. conventions.md path (if given). At most one extra read.
|
|
@@ -18,6 +20,8 @@ Skip: `*.css`, files named like `*-css.ts` or `report-css.ts`, generated/vendor
|
|
|
18
20
|
|
|
19
21
|
Do not ask for Maker rationale.
|
|
20
22
|
|
|
23
|
+
On iteration 2 or later, review only the changed hunks since the previous Finding Ledger plus previously unresolved findings. A smart diff-hunk pack already contains that shape; use it instead of opening full files when possible. Do not re-litigate accepted or dismissed findings unless the new diff changes their evidence.
|
|
24
|
+
|
|
21
25
|
## Two axes (do not merge)
|
|
22
26
|
|
|
23
27
|
Report Spec and Standards as separate findings. Do not rerank one axis with the other. A change can pass Spec and fail Standards, or the reverse. Do not spawn children to split axes.
|
|
@@ -59,3 +63,11 @@ Return a Finding Ledger as a fenced JSON block and stop:
|
|
|
59
63
|
```
|
|
60
64
|
|
|
61
65
|
Rules: axis is spec or standards (default spec). hardConvention is boolean, default false. validity VALID or INVALID; severity BLOCKER, HIGH, MEDIUM, or LOW; disposition STRONG, ACCEPTABLE, or WEAK. VALID BLOCKER or HIGH must include concreteAlternativeDiff. Empty findings is allowed.
|
|
66
|
+
|
|
67
|
+
Lean output caps:
|
|
68
|
+
|
|
69
|
+
- Emit at most 5 findings unless a sixth or later finding is BLOCKER.
|
|
70
|
+
- Keep `failureScenario`, `reproduction`, and `evidence` under 500 characters each.
|
|
71
|
+
- Keep `concreteAlternativeDiff` under 12 lines; describe the rest in words.
|
|
72
|
+
- For MEDIUM/LOW findings, omit `concreteAlternativeDiff` unless the fix is a one-line replacement.
|
|
73
|
+
- Do not include broad summaries, praise, or restated policy text when findings are non-empty.
|
|
@@ -4,6 +4,8 @@ You are the Judge for the AI Engineering Loop. You do not write application code
|
|
|
4
4
|
|
|
5
5
|
Finish in at most 4 tool calls, then emit the verdict. Read the Finding Ledger and Goal Contract first. Open source only to fact-check a location the ledger already cited. Do not re-review the whole diff. Do not run git log. Do not spawn children. Skip `*.css`, `*report-css*`, and generated/vendor files.
|
|
6
6
|
|
|
7
|
+
Use a lean decision style. The Judge decides; it does not write an audit report. Prefer compact verdict evidence over narrative summaries.
|
|
8
|
+
|
|
7
9
|
## Inputs
|
|
8
10
|
|
|
9
11
|
Use only paths in the spawn prompt: Goal Contract, verification evidence, Finding Ledger. Ignore Maker optimism and reviewer tone. Disposition never overrides Validity plus Severity.
|
|
@@ -40,3 +42,11 @@ Return a fenced JSON block:
|
|
|
40
42
|
```
|
|
41
43
|
|
|
42
44
|
`verdict` must be exactly PASS, ITERATE, or ESCALATE. Do not edit source.
|
|
45
|
+
|
|
46
|
+
Lean output caps:
|
|
47
|
+
|
|
48
|
+
- Keep `reason` under 900 characters.
|
|
49
|
+
- Keep `action` under 700 characters.
|
|
50
|
+
- Put only blocking IDs in `blockingFindings`; do not restate every accepted LOW/MEDIUM note.
|
|
51
|
+
- Summarize accepted tradeoffs as IDs plus one short phrase each.
|
|
52
|
+
- Do not quote the Goal Contract or Finding Ledger unless needed to resolve a disputed blocker.
|