ai-engineering-loop 1.0.0

package/profiles/web-app.md

@@ -0,0 +1,65 @@
+# Project Profile: `web-app`
+
+## 1. Profile Definition
+
+- **Archetype**: Frontend Web Applications, Single-Page Applications (SPAs), SSR/SSG Portals (Next.js, Remix, Vite, React, Vue, Svelte, Angular).
+- **Core Environment**: Modern web browser runtimes, DOM APIs, CSSOM, client-side rendering engines.
+
+---
+
+## 2. Engineering & Architecture Characteristics
+
+- **Design System & Tokens**: Strict adherence to design tokens (colors, spacing, typography, elevation). Zero arbitrary hardcoded hex codes or ad-hoc margins.
+- **Component Hierarchy**: Clear separation between dumb presentational components, smart container components, and global state hooks.
+- **Semantic HTML**: Proper use of `<main>`, `<nav>`, `<article>`, `<header>`, `<button>`, `<dialog>` rather than nested `<div>` soup.
+- **Client State Management**: Explicit tracking of loading, error, empty, and populated UI states.
+
+---
+
+## 3. Verification Expectations
+
+When working in a `web-app` repository, deterministic verification should prioritize:
+
+1. **Component & Unit Testing**: Vitest / Jest + React Testing Library (verifying user-facing interactions, role queries, and state transitions).
+2. **Type Safety**: `tsc --noEmit` on frontend types, props, and API response shapes.
+3. **Linting & Accessibility**: `eslint-plugin-jsx-a11y`, CSS linting.
+4. **Build & Bundling**: Production bundle build (`npm run build`) ensuring zero missing assets, broken imports, or bundle size regressions.
+5. **Browser Verification**: When visual changes occur, run Playwright / Cypress smoke tests or DOM inspections.
+
+---
+
+## 4. Active Review Domains for Devil's Advocate
+
+When reviewing diffs in a `web-app` project, the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) activates these targeted checks:
+
+```mermaid
+flowchart LR
+    DA[Devil's Advocate] --> R1[1. UI & Responsive Layout]
+    DA --> R2[2. Accessibility: a11y & ARIA]
+    DA --> R3[3. Client State & Lifecycle]
+    DA --> R4[4. Core Web Vitals & Performance]
+    DA --> R5[5. Web Security: XSS & CSRF]
+    DA --> R6[6. Component Testing Gaps]
+```
+
+### 1. UI & Responsive Layout
+- Does the layout break or overflow horizontally on small viewport widths (320px–390px)?
+- Are modal dialogs, popovers, and dropdowns properly trapped or positioned using standard APIs?
+- Are dark/light theme tokens respected?
+
+### 2. Accessibility (a11y)
+- Are interactive elements accessible via keyboard (`Tab`, `Enter`, `Escape`)?
+- Do icons have `aria-hidden="true"` or descriptive text for screen readers?
+- Are color contrast ratios compliant with WCAG AA standards?
+
+### 3. Client State & Lifecycle
+- Are event listeners, interval timers, and WebSocket subscriptions cleaned up on unmount?
+- Are loading skeletons and error retry banners implemented for async network fetches?
+
+### 4. Core Web Vitals & Performance
+- Are images optimized with explicit `width`, `height`, and modern formats (`webp`, `avif`)?
+- Does the change introduce heavy client-side dependencies that inflate bundle size?
+
+### 5. Web Security
+- Is user-generated content safely escaped to prevent Cross-Site Scripting (XSS)?
+- Are sensitive auth tokens kept in `HttpOnly` cookies rather than `localStorage` where appropriate?

package/scripts/init.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+
+# AI Engineering Loop — One-line Project Initializer
+# Usage: curl -fsSL https://raw.githubusercontent.com/egagofur/ai-engineering-loop/main/scripts/init.sh | bash
+
+set -e
+
+echo -e "\033[1;36m==> AI Engineering Loop: Initializing Project Context...\033[0m"
+
+if [ -d ".ai-engineering-loop" ]; then
+  echo -e "\033[1;32m✓ .ai-engineering-loop/ already exists in this repository.\033[0m"
+  exit 0
+fi
+
+mkdir -p .ai-engineering-loop
+
+# Detect project name
+PROJECT_NAME=$(basename "$PWD")
+PROFILE="backend-api"
+
+# Infer basic profile
+if [ -f "pnpm-workspace.yaml" ] || [ -f "turbo.json" ] || [ -d "apps" ]; then
+  PROFILE="monorepo"
+elif [ -f "next.config.js" ] || [ -f "next.config.mjs" ] || [ -f "vite.config.ts" ]; then
+  PROFILE="web-app"
+elif [ -f "pubspec.yaml" ]; then
+  PROFILE="mobile-app"
+elif [ -f "go.mod" ] || [ -f "Cargo.toml" ] || [ -f "requirements.txt" ]; then
+  PROFILE="backend-api"
+fi
+
+echo "Creating .ai-engineering-loop/ with profile: $PROFILE"
+
+cat <<EOF > .ai-engineering-loop/config.md
+# Project Configuration
+
+## Metadata
+- **project_name**: "$PROJECT_NAME"
+- **project_profile**: "$PROFILE"
+- **default_base_branch**: "main"
+EOF
+
+cat <<EOF > .ai-engineering-loop/architecture.md
+# Project Architecture
+
+## System Overview
+Discovered architecture for $PROJECT_NAME ($PROFILE).
+
+## Boundary Invariants
+- Preserve existing component boundaries and module isolation.
+- Zero cyclic dependencies.
+EOF
+
+cat <<EOF > .ai-engineering-loop/conventions.md
+# Project Conventions
+
+## Code Standards
+- File naming: kebab-case or standard project convention.
+- Error handling: Use domain-specific errors; zero empty catch blocks.
+
+## Forbidden Anti-Patterns
+- Zero speculative TODOs or dead code.
+- Never commit private secrets or credentials.
+EOF
+
+cat <<EOF > .ai-engineering-loop/verification.md
+# Project Verification Commands
+
+## Commands
+- **test_unit**: \`npm test\`
+- **typecheck**: \`npx tsc --noEmit\`
+- **lint**: \`npx eslint --fix\`
+- **build**: \`npm run build\`
+EOF
+
+cat <<EOF > .ai-engineering-loop/adapter.md
+# Project Delivery Adapter Configuration
+
+## Delivery Pipeline
+- **adapter_type**: "standard"
+- **default_target_branch**: "main"
+EOF
+
+echo -e "\033[1;32m✓ .ai-engineering-loop/ successfully initialized!\033[0m"
+echo -e "You can now run the AI Engineering Loop on this repository."

package/templates/repo-config/adapter.md

@@ -0,0 +1,11 @@
+# Project Delivery Adapter Configuration
+
+## Delivery Settings
+- **adapter_type**: "github" # dot | github | gitlab | custom
+- **repository**: "organization/my-service"
+- **default_target_branch**: "main"
+- **notification_webhook**: "https://hooks.slack.com/services/..." # Optional
+
+## Multi-Branch Settings (If applicable)
+- **enable_multi_branch**: false
+- **branches**: []

package/templates/repo-config/architecture.md

@@ -0,0 +1,15 @@
+# Project Architecture
+
+## System Overview
+[Brief summary of what this project does and its core domain responsibility.]
+
+## Layers & Directory Boundaries
+- `src/controllers/`: Ingress HTTP / RPC controllers. Validates input schemas, delegates to services.
+- `src/services/`: Pure business logic and domain lifecycle workflows.
+- `src/repositories/`: Database queries and ORM operations.
+- `src/integrations/`: Third-party API clients and message brokers.
+
+## Critical Invariants
+- Controllers must never execute direct database queries.
+- Repositories must never handle HTTP request or response objects.
+- All transactional workflows spanning $>1$ repository write must use `prisma.$transaction`.

package/templates/repo-config/config.md

@@ -0,0 +1,11 @@
+# Project Configuration
+
+## Metadata
+- **project_name**: "my-service"
+- **project_profile**: "backend-api" # web-app | backend-api | mobile-app | library | monorepo
+- **languages**:
+  - TypeScript (Node.js 20.x)
+- **frameworks**:
+  - NestJS
+  - Prisma ORM
+- **default_base_branch**: "main"

package/templates/repo-config/conventions.md

@@ -0,0 +1,16 @@
+# Project Conventions
+
+## Code Standards & Style
+- File naming: `kebab-case.ts` (e.g. `user-service.ts`, `auth-guard.ts`).
+- Test file placement: Colocated `*.spec.ts` alongside implementation.
+- Types: Explicit return types on all exported service functions.
+
+## Error Handling
+- Use domain errors inheriting from `AppException(message, status, code)`.
+- Never throw generic `new Error()`.
+- Never leave empty catch blocks.
+
+## Forbidden Anti-Patterns
+- Zero `any` types (use `unknown` with type guards).
+- Zero raw unescaped SQL strings.
+- Do not import external modules directly into domain entities.

package/templates/repo-config/verification.md

@@ -0,0 +1,13 @@
+# Project Verification Commands
+
+## Commands
+- **test_unit**: `npm run test:unit`
+- **test_all**: `npm run test`
+- **typecheck**: `npx tsc --noEmit`
+- **lint**: `npx eslint --fix`
+- **build**: `npm run build`
+- **e2e**: `npm run test:e2e` # Optional
+
+## Verification Notes
+- Unit test suite should complete within 30 seconds.
+- Database integration tests require test container (`docker compose up -d postgres-test`).