ai-engineering-loop 1.0.21 → 1.1.0

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.
Files changed (89) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +7 -3
  2. package/.claude/skills/ai-engineering-loop/SKILL.md +13 -7
  3. package/.gemini/skills/ai-engineering-loop/SKILL.md +13 -7
  4. package/.grok/skills/ai-engineering-loop/SKILL.md +13 -7
  5. package/README.md +26 -3
  6. package/SECURITY.md +23 -0
  7. package/SUPPORT.md +28 -0
  8. package/bin/ai-engineering-loop.js +255 -3
  9. package/core/artifact-gates.md +49 -0
  10. package/evals/README.md +35 -0
  11. package/evals/cases/01-stale-verification.json +17 -0
  12. package/evals/cases/02-vague-verification.json +16 -0
  13. package/evals/cases/03-missing-ac-evidence.json +17 -0
  14. package/evals/cases/04-hallucinated-citation.json +17 -0
  15. package/evals/cases/05-prompt-injection.json +17 -0
  16. package/evals/cases/06-source-secret.json +16 -0
  17. package/evals/cases/07-log-secret.json +16 -0
  18. package/evals/cases/08-symlink-escape.json +16 -0
  19. package/evals/cases/09-authorization-bypass.json +16 -0
  20. package/evals/cases/10-payment-idempotency.json +16 -0
  21. package/evals/cases/11-concurrent-update.json +16 -0
  22. package/evals/cases/12-swallowed-error.json +16 -0
  23. package/evals/cases/13-happy-path-only.json +17 -0
  24. package/evals/cases/14-invalid-finding-axis.json +16 -0
  25. package/evals/cases/15-blocker-without-alternative.json +16 -0
  26. package/evals/cases/16-unsupported-pass.json +17 -0
  27. package/evals/cases/17-soft-standard.json +16 -0
  28. package/evals/cases/18-iteration-ceiling.json +17 -0
  29. package/evals/cases/19-safe-documentation-change.json +17 -0
  30. package/evals/cases/20-valid-boundary-feature.json +18 -0
  31. package/lib/doctor.js +98 -0
  32. package/lib/escalation.js +192 -0
  33. package/lib/evaluation.js +137 -0
  34. package/lib/gates.js +315 -0
  35. package/lib/orchestration.js +5 -1
  36. package/lib/run-state.js +221 -0
  37. package/lib/safe-context.js +191 -0
  38. package/lib/sync-hosts.js +6 -5
  39. package/package.json +12 -9
  40. package/policies/model-escalation.md +41 -0
  41. package/schemas/delivery.schema.json +14 -0
  42. package/schemas/finding-ledger.schema.json +27 -0
  43. package/schemas/goal-contract.schema.json +32 -0
  44. package/schemas/verdict.schema.json +17 -0
  45. package/schemas/verification.schema.json +32 -0
  46. package/docs/antigravity-feasibility.md +0 -92
  47. package/docs/claude-code-feasibility.md +0 -80
  48. package/docs/grok-cli-feasibility.md +0 -99
  49. package/docs/migration-plan.md +0 -70
  50. package/examples/backend-api/payment-idempotency/README.md +0 -33
  51. package/examples/backend-api/payment-idempotency/goal-contract.md +0 -33
  52. package/examples/backend-api/payment-idempotency/judge-verdict.md +0 -28
  53. package/examples/backend-api/payment-idempotency/review-findings.md +0 -50
  54. package/examples/dot/status-display/README.md +0 -23
  55. package/examples/dot/status-display/delivery-report.md +0 -41
  56. package/examples/dot/status-display/goal-contract.md +0 -46
  57. package/examples/dot/status-display/judge-verdict.md +0 -44
  58. package/examples/dot/status-display/review-findings.md +0 -63
  59. package/examples/initialization/README.md +0 -19
  60. package/examples/initialization/discovery-trace.md +0 -63
  61. package/examples/initialization/generated-context.md +0 -110
  62. package/examples/mobile-app/offline-sync-queue/README.md +0 -33
  63. package/examples/mobile-app/offline-sync-queue/goal-contract.md +0 -32
  64. package/examples/mobile-app/offline-sync-queue/judge-verdict.md +0 -27
  65. package/examples/mobile-app/offline-sync-queue/review-findings.md +0 -30
  66. package/scripts/init.sh +0 -106
  67. package/templates/repo-config/adapter.md +0 -11
  68. package/templates/repo-config/adr-readme.md +0 -33
  69. package/templates/repo-config/architecture.md +0 -15
  70. package/templates/repo-config/claude-permissions.json +0 -10
  71. package/templates/repo-config/config.md +0 -11
  72. package/templates/repo-config/conventions.md +0 -16
  73. package/templates/repo-config/glossary.md +0 -18
  74. package/templates/repo-config/lessons.md +0 -8
  75. package/templates/repo-config/verification.md +0 -13
  76. package/templates/repo-config/workflow.md +0 -25
  77. package/tests/capability-selection.test.js +0 -207
  78. package/tests/claimed-vs-reality.test.js +0 -27
  79. package/tests/dot-branch-policy.test.js +0 -65
  80. package/tests/generate-adapter.test.js +0 -80
  81. package/tests/generate-workflow.test.js +0 -180
  82. package/tests/grok-runtime.test.js +0 -201
  83. package/tests/intern-catalog.test.js +0 -72
  84. package/tests/living-context.test.js +0 -61
  85. package/tests/no-company-leak.test.js +0 -82
  86. package/tests/orchestration.test.js +0 -368
  87. package/tests/qa-delivery-template.test.js +0 -90
  88. package/tests/skill-host-compat.test.js +0 -406
  89. package/tests/sync-hosts.test.js +0 -168
@@ -1,63 +0,0 @@
1
- # Adversarial Review Findings & Triage: Request Display Status Fix
2
-
3
- ## 1. Review Summary
4
-
5
- - **Reviewer**: Devil's Advocate Agent
6
- - **Target Branch**: `main...fix/request-display-status`
7
- - **Total Findings**: 2
8
- - **Blocking (SEV-1/2)**: 1
9
- - **Non-Blocking / Invalid**: 1
10
-
11
- ---
12
-
13
- ## 2. Findings Ledger
14
-
15
- ### Finding COR-001: Missing null safety when iterating `lineItems`
16
-
17
- - **Severity**: `HIGH` (SEV-2)
18
- - **Category**: `Correctness`
19
- - **Location**: `src/server/requests/utils/resolve-display-status.ts:34-41`
20
- - **Evidence**:
21
-
22
- ```typescript
23
- const hasPending = confirmation.lineItems.some(
24
- (item) => item.status === "NEED_APPROVAL"
25
- );
26
- ```
27
-
28
- - **Problem**:
29
- If `confirmation.lineItems` is `null` or `undefined` (legacy rows), `.some()` throws `TypeError`.
30
- - **Impact**:
31
- Pagination API crashes for historical records.
32
- - **Recommendation**:
33
-
34
- ```diff
35
- - const hasPending = confirmation.lineItems.some(
36
- + const hasPending = (confirmation.lineItems ?? []).some(
37
- (item) => item.status === "NEED_APPROVAL"
38
- );
39
- ```
40
-
41
- - **Confidence**: `HIGH`
42
- - **Status**: `TRIAGED_VALID`
43
- - **Resolution**:
44
- Maker applied `(confirmation.lineItems ?? [])` and added `should return APPROVED when lineItems is null or undefined`.
45
-
46
- ---
47
-
48
- ### Finding MAINT-001: Suggestion to convert helper into an abstract factory class
49
-
50
- - **Severity**: `LOW` (SEV-4)
51
- - **Category**: `Maintainability`
52
- - **Location**: `src/server/requests/utils/resolve-display-status.ts:1-50`
53
- - **Evidence**:
54
- Utility is `export function resolveRequestDisplayStatus(...)`.
55
- - **Problem**:
56
- Reviewer wanted a Strategy/Factory for future calculator swaps.
57
- - **Impact**:
58
- None. Pure functions match this repo.
59
- - **Recommendation**: Refactor to `class StatusCalculatorFactory`.
60
- - **Confidence**: `LOW`
61
- - **Status**: `TRIAGED_INVALID`
62
- - **Triage Reason**:
63
- Speculative overengineering. Constraint: surgical change, no extra abstractions.
@@ -1,19 +0,0 @@
1
- # Reference Example: Automatic Project Initialization & Discovery
2
-
3
- ## 1. Overview & Scenario
4
-
5
- This walkthrough demonstrates how the **AI Engineering Loop** automatically initializes an unconfigured full-stack TypeScript and Go monorepo (`acme-platform`) that contains **zero** existing `.ai-engineering-loop/` configuration.
6
-
7
- ### The Codebase State:
8
- - **Repository**: `acme-corp/acme-platform`
9
- - **Existing Config**: `pnpm-workspace.yaml`, `turbo.json`, `apps/web/package.json` (Next.js), `apps/api/go.mod` (Go/Gin), `packages/ui/`
10
- - **Initial Status**: No `.ai-engineering-loop/` folder present.
11
-
12
- ---
13
-
14
- ## 2. Walkthrough Artifacts
15
-
16
- 1. **[Discovery Execution Trace (`discovery-trace.md`)](./discovery-trace.md)**:
17
- - Full 5-pass log of directory inspection, manifest parsing, script discovery, architecture tracing, and second-pass quality check.
18
- 2. **[Generated Context Artifacts (`generated-context.md`)](./generated-context.md)**:
19
- - The exact evidence-based `.ai-engineering-loop/` files generated automatically by the agent without user intervention.
@@ -1,63 +0,0 @@
1
- # Discovery Execution Trace: `acme-platform`
2
-
3
- ## 1. Trigger & Initial Detection
4
-
5
- ```text
6
- [ENGINE] Initializing workspace in /workspaces/acme-platform
7
- [ENGINE] Checking for .ai-engineering-loop/... NOT FOUND.
8
- [ENGINE] Triggering State B: Autonomous Project Initialization & Discovery.
9
- ```
10
-
11
- ---
12
-
13
- ## 2. The 5-Pass Discovery Log
14
-
15
- ### Pass 1: Topology & Workspace Inspection
16
- - `list_dir /workspaces/acme-platform`:
17
- - `apps/` (contains `web/`, `api/`)
18
- - `packages/` (contains `ui/`, `database/`, `shared/`)
19
- - `pnpm-workspace.yaml` (detected `pnpm` monorepo)
20
- - `turbo.json` (detected Turborepo pipeline)
21
- - **Profile Binding**: Bound [`profiles/monorepo.md`](../../profiles/monorepo.md).
22
-
23
- ### Pass 2: Manifests & Verification Commands Discovery
24
- - Parsed `package.json` (root):
25
- - `"test"`: `"turbo run test"`
26
- - `"typecheck"`: `"turbo run typecheck"`
27
- - `"lint"`: `"turbo run lint"`
28
- - `"build"`: `"turbo run build"`
29
- - Parsed `apps/api/go.mod`:
30
- - Go 1.22, Gin framework, pgx
31
- - Extracted Commands:
32
- - Unit Tests: `pnpm test` (or `pnpm --filter @acme/web test` for focused web)
33
- - Typecheck: `pnpm typecheck`
34
- - Linter: `pnpm lint`
35
- - Build: `pnpm build`
36
-
37
- ### Pass 3: Architecture & Invariant Mapping
38
- - **Presentation**: Next.js 14 App Router in `apps/web/src/app`, Gin REST API in `apps/api/cmd/server`.
39
- - **Data Access**: PostgreSQL + Prisma in `packages/database`.
40
- - **Shared UI**: Tailwind + Radix UI in `packages/ui`.
41
- - **Boundaries**: `packages/ui` and `packages/database` are shared dependencies; `apps/web` must not import `apps/api` internal code.
42
-
43
- ### Pass 4: Observed Conventions Extraction
44
- - File naming: `kebab-case` throughout `apps/web` and `packages/ui`.
45
- - Error handling: Go API returns `{"error": {"code": "...", "message": "..."}}`.
46
- - Git remote: `origin -> https://github.com/acme-corp/acme-platform.git`.
47
- - Adapter: Bound GitHub Adapter.
48
-
49
- ### Pass 5: Second-Pass Context Quality Audit
50
- - Evidence check: 100% of claims attributed to files.
51
- - Secret check: `.env` and `.env.local` skipped; `.env.example` verified safe. Zero leaked credentials.
52
- - Conciseness check: 180 total lines generated across `.ai-engineering-loop/`.
53
- - Status: **PASSED QUALITY AUDIT**.
54
-
55
- ---
56
-
57
- ## 3. Completion & Hand-off
58
-
59
- ```text
60
- [ENGINE] Generated .ai-engineering-loop/ (config.md, architecture.md, conventions.md, verification.md, adapter.md, glossary.md, adrs/README.md)
61
- [ENGINE] Project Context successfully initialized!
62
- [ENGINE] Proceeding to Goal Contract formulation...
63
- ```
@@ -1,110 +0,0 @@
1
- # Generated Context Artifacts: `acme-platform`
2
-
3
- Below are the files generated automatically inside `/workspaces/acme-platform/.ai-engineering-loop/` (including `glossary.md` and `adrs/README.md`):
4
-
5
- ---
6
-
7
- ## 1. `.ai-engineering-loop/config.md`
8
-
9
- ```markdown
10
- # Project Configuration
11
-
12
- ## Metadata
13
- - **project_name**: "acme-platform"
14
- - **project_profile**: "monorepo" # Archetype bound from profiles/monorepo.md
15
- - **languages**:
16
- - TypeScript 5.4 (Node.js 20.x)
17
- - Go 1.22
18
- - **frameworks**:
19
- - Next.js 14 (App Router)
20
- - Gin Web Framework
21
- - Prisma ORM
22
- - **package_manager**: "pnpm" (Turborepo workspace)
23
- - **default_base_branch**: "main"
24
-
25
- ## Evidence
26
- - Topology: `pnpm-workspace.yaml`, `turbo.json`
27
- - Apps: `apps/web/package.json`, `apps/api/go.mod`
28
- - Shared: `packages/ui/package.json`, `packages/database/prisma/schema.prisma`
29
- ```
30
-
31
- ---
32
-
33
- ## 2. `.ai-engineering-loop/architecture.md`
34
-
35
- ```markdown
36
- # Project Architecture
37
-
38
- ## System Overview
39
- Full-stack monorepo featuring a Next.js 14 web application, a Go backend API service, and shared UI/database packages.
40
-
41
- ## Applications & Packages
42
- - `apps/web`: Next.js 14 frontend client rendering UI.
43
- - `apps/api`: Go Gin REST service handling payments and user records.
44
- - `packages/ui`: Shared React/Tailwind component library.
45
- - `packages/database`: Centralized Prisma client and database schemas.
46
-
47
- ## Boundary Invariants
48
- - `packages/ui` must not import backend API logic.
49
- - `apps/web` must not connect directly to the database; it queries `apps/api` via REST.
50
- - Shared packages must maintain zero cyclic dependencies.
51
-
52
- ## Evidence & Confidence
53
- - Observed from: `apps/`, `packages/`, `turbo.json`
54
- - Confidence: HIGH
55
- ```
56
-
57
- ---
58
-
59
- ## 3. `.ai-engineering-loop/conventions.md`
60
-
61
- ```markdown
62
- # Project Conventions
63
-
64
- ## Code Standards
65
- - File naming: `kebab-case` for TypeScript components and Go files.
66
- - Test placement: Colocated `*.test.tsx` in `apps/web`; `*_test.go` in `apps/api`.
67
- - Design tokens: Use Tailwind utility classes with colors defined in `packages/ui/tailwind.config.js`.
68
-
69
- ## Forbidden Anti-Patterns
70
- - Zero `any` types in TypeScript packages.
71
- - Zero unchecked error returns in Go (`if err != nil` is mandatory).
72
- - Do not commit or hardcode environment URLs.
73
- ```
74
-
75
- ---
76
-
77
- ## 4. `.ai-engineering-loop/verification.md`
78
-
79
- ```markdown
80
- # Project Verification Commands
81
-
82
- ## Workspace Package Manager
83
- pnpm (Turborepo)
84
-
85
- ## Commands
86
- - **test_unit**: `pnpm test`
87
- - **test_scoped**: `pnpm --filter <package-name> test`
88
- - **typecheck**: `pnpm typecheck`
89
- - **lint**: `pnpm lint`
90
- - **build**: `pnpm build`
91
-
92
- ## Required Verification by Scope
93
- - **Web changes**: `pnpm --filter @acme/web test` and `pnpm --filter @acme/web typecheck`.
94
- - **API changes**: `cd apps/api && go test -v ./...` and `golangci-lint run`.
95
- - **Database changes**: `pnpm --filter @acme/database test`.
96
- ```
97
-
98
- ---
99
-
100
- ## 5. `.ai-engineering-loop/adapter.md`
101
-
102
- ```markdown
103
- # Project Delivery Adapter Configuration
104
-
105
- ## Delivery Pipeline
106
- - **adapter_type**: "github"
107
- - **repository**: "acme-corp/acme-platform"
108
- - **default_target_branch**: "main"
109
- - **ci_workflows**: GitHub Actions (`.github/workflows/ci.yml`)
110
- ```
@@ -1,33 +0,0 @@
1
- # Reference Example: Mobile App Offline Sync Queue
2
-
3
- ## 1. Scenario Overview
4
-
5
- This walkthrough demonstrates the **AI Engineering Loop** operating in a **Mobile Application** repository (`mobile-app` profile) for a field survey application built in Flutter / SQLite.
6
-
7
- ### The Problem
8
- Field inspectors working in remote areas without cellular coverage experienced loss of submitted inspection forms when the application was closed or terminated by the OS before regaining an internet connection.
9
-
10
- ---
11
-
12
- ## 2. Dynamic Context Resolution
13
-
14
- ```text
15
- Engine: AI Engineering Loop Core
16
- Profile: profiles/mobile-app.md
17
- Repo Config: inspector-app/.ai-engineering-loop/ (Flutter 3.22, sqflite, Riverpod)
18
- Task: Implement persistent offline SQLite mutation queue with exponential backoff sync
19
- ```
20
-
21
- ---
22
-
23
- ## 3. Walkthrough Artifacts
24
-
25
- 1. **[Goal Contract (`goal-contract.md`)](./goal-contract.md)**:
26
- - AC-1: All form submissions persist immediately to local SQLite `mutation_queue` table before network dispatch.
27
- - AC-2: Background sync engine triggers on network restoration with exponential backoff.
28
- - AC-3: OS suspension / app kill must not drop un-synced items.
29
- 2. **[Adversarial Review Findings (`review-findings.md`)](./review-findings.md)**:
30
- - Devil's Advocate activates `mobile-app` rules (offline persistence, lifecycle, battery).
31
- - Flags missing disk write error handling when device storage is full (`PERF-001`).
32
- 3. **[Judge Verdict (`judge-verdict.md`)](./judge-verdict.md)**:
33
- - Audits Flutter unit & mock network tests, verifies 100% pass, and issues `PASS` verdict.
@@ -1,32 +0,0 @@
1
- # Goal Contract: Offline Mutation Queue & Sync Engine
2
-
3
- ## 1. Objective
4
- Implement an offline-first transactional queue in SQLite that captures user inspection submissions locally and synchronizes reliably with the cloud API upon network reconnection.
5
-
6
- ## 2. Business Outcome & User Lifecycle Impact
7
- - **Field Inspectors**: Can complete and save survey reports anywhere with zero risk of data loss.
8
- - **Operations**: Automatic background upload with zero manual re-entry.
9
-
10
- ## 3. Acceptance Criteria (AC)
11
- - [ ] **AC-1**: Submissions write to local SQLite `mutation_queue` with status `PENDING` before network attempt.
12
- - [ ] **AC-2**: Connectivity changes trigger FIFO queue processing with max 3 retry attempts per item.
13
- - [ ] **AC-3**: Simulated app kill during background sync resumes cleanly upon next launch.
14
- - [ ] **AC-4**: Zero data loss under intermittent network flapping (3G/offline transitions).
15
-
16
- ## 4. Technical Constraints
17
- - Flutter 3.22, Dart 3.4, `sqflite` for local DB, `connectivity_plus` for network state.
18
- - Pure Dart logic for sync manager with zero direct UI widget dependencies.
19
-
20
- ## 5. Out of Scope
21
- - Modifying survey form UI layout or camera image capture compression.
22
-
23
- ## 6. Verification Requirements
24
- - **Unit & Mock Tests**: `flutter test test/core/sync/offline_queue_test.dart`
25
- - **Static Analysis**: `dart analyze`
26
- - **Build Check**: `flutter build bundle`
27
-
28
- ## 7. Definition of Done (DoD)
29
- - [ ] All AC-1 through AC-4 proven via unit & repository test suites.
30
- - [ ] Static analysis 0 issues.
31
- - [ ] Devil's Advocate review conducted with 0 unresolved blocking findings.
32
- - [ ] Judge issues PASS verdict.
@@ -1,27 +0,0 @@
1
- # Judge Evaluation Report: Offline Sync Queue
2
-
3
- ## 1. Executive Verdict
4
- - **Verdict**: `PASS`
5
- - **Iteration**: `Iteration 2 of 3`
6
- - **Confidence**: `HIGH`
7
-
8
- ---
9
-
10
- ## 2. Deterministic Verification Audit
11
-
12
- | Check | Command Executed | Raw Result | Status |
13
- |---|---|---|:---:|
14
- | **Unit & Sync Tests** | `flutter test test/core/sync/` | `00:04 +18: All tests passed!` | ✅ PASS |
15
- | **Static Analysis** | `dart analyze` | `No issues found! (ran in 1.8s)` | ✅ PASS |
16
- | **Asset Bundle** | `flutter build bundle` | `Bundle built successfully.` | ✅ PASS |
17
-
18
- ---
19
-
20
- ## 3. Finding Triage Audit
21
- - **ERR-001 (High - SQLite Disk Full Crash)**: Resolved by wrapping insert operations with domain exception handlers and fallback telemetry. **Status: RESOLVED & VERIFIED**.
22
-
23
- ---
24
-
25
- ## 4. Hand-off
26
- All Definition of Done criteria are satisfied.
27
- **Authorized next action**: Proceed to designated mobile release pipeline.
@@ -1,30 +0,0 @@
1
- # Adversarial Review Findings: Offline Sync Queue
2
-
3
- ## 1. Review Summary
4
- - **Reviewer**: Devil's Advocate Agent (Profile: `mobile-app`)
5
- - **Active Review Domains**: Offline Sync, Lifecycle, Permissions, Battery/Network Hygiene
6
- - **Total Findings**: 1
7
- - **Blocking (SEV-1/2)**: 1
8
-
9
- ---
10
-
11
- ## 2. Findings Ledger
12
-
13
- ### Finding ERR-001: Missing unhandled SQLite disk full exception handling
14
- - **Severity**: `HIGH` (SEV-2)
15
- - **Category**: `Error Handling & Persistence`
16
- - **Location**: `lib/core/sync/sqlite_mutation_store.dart:45-56`
17
- - **Evidence**:
18
- ```dart
19
- await _db.insert('mutation_queue', item.toMap());
20
- ```
21
- - **Problem**:
22
- If the device filesystem runs out of storage space (common on low-end inspection tablets), `_db.insert()` throws an unhandled `DatabaseException` that bubbles up and crashes the UI layer, preventing the user from navigating or seeing an alert.
23
- - **Impact**:
24
- App crash on disk full errors with uninformative logs.
25
- - **Recommendation**:
26
- Wrap write operations in domain-specific `StorageException` handling and surface a user-friendly "Device Storage Low" snackbar notification.
27
- - **Confidence**: `HIGH`
28
- - **Status**: `TRIAGED_VALID`
29
- - **Resolution**:
30
- Maker Agent wrapped repository writes in `try/catch (DatabaseException)` with fallback error telemetry and added unit test `should throw StorageFullException gracefully when disk is full`.
package/scripts/init.sh DELETED
@@ -1,106 +0,0 @@
1
- #!/usr/bin/env bash
2
-
3
- # AI Engineering Loop — One-line Project Initializer
4
- # Usage: curl -fsSL https://raw.githubusercontent.com/egagofur/ai-engineering-loop/main/scripts/init.sh | bash
5
-
6
- set -e
7
-
8
- echo -e "\033[1;36m==> AI Engineering Loop: Initializing Project Context...\033[0m"
9
-
10
- if [ -d ".ai-engineering-loop" ]; then
11
- echo -e "\033[1;32m✓ .ai-engineering-loop/ already exists in this repository.\033[0m"
12
- exit 0
13
- fi
14
-
15
- mkdir -p .ai-engineering-loop
16
-
17
- # Detect project name
18
- PROJECT_NAME=$(basename "$PWD")
19
- PROFILE="backend-api"
20
-
21
- # Infer basic profile
22
- if [ -f "pnpm-workspace.yaml" ] || [ -f "turbo.json" ] || [ -d "apps" ]; then
23
- PROFILE="monorepo"
24
- elif [ -f "next.config.js" ] || [ -f "next.config.mjs" ] || [ -f "vite.config.ts" ]; then
25
- PROFILE="web-app"
26
- elif [ -f "pubspec.yaml" ]; then
27
- PROFILE="mobile-app"
28
- elif [ -f "go.mod" ] || [ -f "Cargo.toml" ] || [ -f "requirements.txt" ]; then
29
- PROFILE="backend-api"
30
- fi
31
-
32
- echo "Creating .ai-engineering-loop/ with profile: $PROFILE"
33
-
34
- cat <<EOF > .ai-engineering-loop/config.md
35
- # Project Configuration
36
-
37
- ## Metadata
38
- - **project_name**: "$PROJECT_NAME"
39
- - **project_profile**: "$PROFILE"
40
- - **default_base_branch**: "main"
41
- EOF
42
-
43
- cat <<EOF > .ai-engineering-loop/architecture.md
44
- # Project Architecture
45
-
46
- ## System Overview
47
- Discovered architecture for $PROJECT_NAME ($PROFILE).
48
-
49
- ## Boundary Invariants
50
- - Preserve existing component boundaries and module isolation.
51
- - Zero cyclic dependencies.
52
- EOF
53
-
54
- cat <<EOF > .ai-engineering-loop/conventions.md
55
- # Project Conventions
56
-
57
- ## Code Standards
58
- - File naming: kebab-case or standard project convention.
59
- - Error handling: Use domain-specific errors; zero empty catch blocks.
60
-
61
- ## Forbidden Anti-Patterns
62
- - Zero speculative TODOs or dead code.
63
- - Never commit private secrets or credentials.
64
- EOF
65
-
66
- cat <<EOF > .ai-engineering-loop/verification.md
67
- # Project Verification Commands
68
-
69
- ## Commands
70
- - **test_unit**: \`npm test\`
71
- - **typecheck**: \`npx tsc --noEmit\`
72
- - **lint**: \`npx eslint --fix\`
73
- - **build**: \`npm run build\`
74
- EOF
75
-
76
- cat <<EOF > .ai-engineering-loop/adapter.md
77
- # Project Delivery Adapter Configuration
78
-
79
- ## Delivery Pipeline
80
- - **adapter_type**: "standard"
81
- - **default_target_branch**: "main"
82
- EOF
83
-
84
- cat <<EOF > .ai-engineering-loop/glossary.md
85
- # Ubiquitous Language
86
-
87
- One term per concept. Use these words in Goal Contracts, tests, and code names.
88
-
89
- ## Terms
90
-
91
- | Term | Meaning | Do not say |
92
- |---|---|---|
93
- | Goal Contract | Frozen Stage 1 acceptance document | "the prompt" |
94
- | Seam | Public interface under test | "the internals" |
95
- EOF
96
-
97
- mkdir -p .ai-engineering-loop/adrs
98
- cat <<EOF > .ai-engineering-loop/adrs/README.md
99
- # Architecture Decision Records
100
-
101
- Write one ADR when Stage 1 grill settles a load-bearing choice.
102
- File name: NNN-short-kebab-title.md
103
- EOF
104
-
105
- echo -e "\033[1;32m✓ .ai-engineering-loop/ successfully initialized!\033[0m"
106
- echo -e "You can now run the AI Engineering Loop on this repository."
@@ -1,11 +0,0 @@
1
- # Project Delivery Adapter Configuration
2
-
3
- ## Delivery Settings
4
- - **adapter_type**: "github" # standard | github | gitlab | dot | custom
5
- - **repository**: "organization/my-service"
6
- - **default_target_branch**: "main"
7
- - **notification_webhook**: "https://hooks.slack.com/services/..." # Optional
8
-
9
- ## Multi-Branch Settings (If applicable)
10
- - **enable_multi_branch**: false
11
- - **branches**: []
@@ -1,33 +0,0 @@
1
- # Architecture Decision Records
2
-
3
- Hard decisions that would otherwise live only in chat. Write one ADR when Stage 1 grill settles a choice that future agents must not re-litigate.
4
-
5
- ## When to write
6
-
7
- - Two viable designs were on the table and one was chosen
8
- - A boundary, schema, or public seam is now load-bearing
9
- - The Goal Contract's Technical Constraints need a durable why
10
-
11
- Do not write an ADR for a typo fix, a local rename, or a test-only change.
12
-
13
- ## File name
14
-
15
- `NNN-short-kebab-title.md` in this directory. Increment `NNN`.
16
-
17
- ## Template
18
-
19
- ```markdown
20
- # ADR NNN: <title>
21
-
22
- ## Status
23
- Accepted | Superseded by ADR NNN
24
-
25
- ## Context
26
- What forced a choice.
27
-
28
- ## Decision
29
- What we chose, in glossary terms.
30
-
31
- ## Consequences
32
- What becomes easier, harder, or forbidden.
33
- ```
@@ -1,15 +0,0 @@
1
- # Project Architecture
2
-
3
- ## System Overview
4
- [Brief summary of what this project does and its core domain responsibility.]
5
-
6
- ## Layers & Directory Boundaries
7
- - `src/controllers/`: Ingress HTTP / RPC controllers. Validates input schemas, delegates to services.
8
- - `src/services/`: Pure business logic and domain lifecycle workflows.
9
- - `src/repositories/`: Database queries and ORM operations.
10
- - `src/integrations/`: Third-party API clients and message brokers.
11
-
12
- ## Critical Invariants
13
- - Controllers must never execute direct database queries.
14
- - Repositories must never handle HTTP request or response objects.
15
- - All transactional workflows spanning $>1$ repository write must use `prisma.$transaction`.
@@ -1,10 +0,0 @@
1
- {
2
- "permissions": {
3
- "allow": [
4
- "Bash(npm run *)",
5
- "Bash(npm test *)",
6
- "Bash(npx *)",
7
- "Bash(git *)"
8
- ]
9
- }
10
- }
@@ -1,11 +0,0 @@
1
- # Project Configuration
2
-
3
- ## Metadata
4
- - **project_name**: "my-service"
5
- - **project_profile**: "backend-api" # web-app | backend-api | mobile-app | library | monorepo
6
- - **languages**:
7
- - TypeScript (Node.js 20.x)
8
- - **frameworks**:
9
- - NestJS
10
- - Prisma ORM
11
- - **default_base_branch**: "main"
@@ -1,16 +0,0 @@
1
- # Project Conventions
2
-
3
- ## Code Standards & Style
4
- - File naming: `kebab-case.ts` (e.g. `user-service.ts`, `auth-guard.ts`).
5
- - Test file placement: Colocated `*.spec.ts` alongside implementation.
6
- - Types: Explicit return types on all exported service functions.
7
-
8
- ## Error Handling
9
- - Use domain errors inheriting from `AppException(message, status, code)`.
10
- - Never throw generic `new Error()`.
11
- - Never leave empty catch blocks.
12
-
13
- ## Forbidden Anti-Patterns
14
- - Zero `any` types (use `unknown` with type guards).
15
- - Zero raw unescaped SQL strings.
16
- - Do not import external modules directly into domain entities.
@@ -1,18 +0,0 @@
1
- # Ubiquitous Language
2
-
3
- One term per concept. Agents and humans use these words in Goal Contracts, tests, code names, and review. Prefer a short term over a 20-word paraphrase.
4
-
5
- Update this file during Stage 1 grill when a term is coined or corrected. Do not invent parallel synonyms.
6
-
7
- ## Terms
8
-
9
- | Term | Meaning | Do not say |
10
- |---|---|---|
11
- | Goal Contract | Frozen Stage 1 acceptance document | "the prompt", "the ticket vibe" |
12
- | Seam | Public interface under test | "the internals", "the private helper" |
13
-
14
- ## How to add a term
15
-
16
- 1. Can this idea be named in 1–4 words?
17
- 2. Does an existing term already cover it? Reuse it.
18
- 3. Add one row. Use the term in the next Goal Contract.
@@ -1,8 +0,0 @@
1
- # Lessons
2
-
3
- Confirmed by a human. One row per lesson. Not a chat transcript. Not a glossary.
4
-
5
- Route elsewhere when it fits: term → glossary.md, code ban → conventions.md, load-bearing design → adrs/.
6
-
7
- | Date | Lesson | Do not |
8
- |---|---|---|
@@ -1,13 +0,0 @@
1
- # Project Verification Commands
2
-
3
- ## Commands
4
- - **test_unit**: `npm run test:unit`
5
- - **test_all**: `npm run test`
6
- - **typecheck**: `npx tsc --noEmit`
7
- - **lint**: `npx eslint --fix`
8
- - **build**: `npm run build`
9
- - **e2e**: `npm run test:e2e` # Optional
10
-
11
- ## Verification Notes
12
- - Unit test suite should complete within 30 seconds.
13
- - Database integration tests require test container (`docker compose up -d postgres-test`).
@@ -1,25 +0,0 @@
1
- # Loop Overlay
2
-
3
- This file adds hooks around the AI Engineering Loop. It does not replace the 8-stage OS.
4
-
5
- ## Required (cannot skip)
6
- - Goal Contract
7
- - verification
8
- - Devil's Advocate
9
- - Judge
10
-
11
- ## Hooks
12
- - **before_grill**: none
13
- - **after_freeze**: none
14
- - **after_pass**: none
15
-
16
- ## Maker intern
17
- - **maker_intern**: none
18
-
19
- Default `none` = parent is Maker. Pick `maker_intern` from this host's catalog (`grok models` or `/models`). Do not type a guessed slug. AEL does not store intern API keys. Devil's Advocate and Judge stay on the parent. Intern cannot skip them.
20
-
21
- ## Optional skips
22
- none
23
-
24
- Allowed optional skips: `blast_radius` (when the change is not business logic), `generate_adapter` (when adapter.md already exists).
25
- Do not list Goal Contract, verification, Devil's Advocate, or Judge here.