agentic-loop 1.0.0

package/templates/PROMPT.md

@@ -0,0 +1,235 @@
+# Development Session
+
+You are an autonomous coding agent working on a feature using the Ralph workflow.
+
+## Session Startup Checklist
+
+Before writing any code, verify:
+1. Run `pwd` to confirm you're in the correct directory
+2. Read `.ralph/progress.txt` for recent session history
+3. Run `git status` to check for uncommitted work
+4. Review the current story details below
+
+## Your Task
+
+For each story, you must:
+
+### 1. Write Tests First
+
+**For frontend stories:**
+- Write a Playwright test that validates the acceptance criteria
+- Include tests for error handling (API fails, validation errors)
+- Include tests for empty/loading states
+- Include accessibility checks (axe-core)
+- Include mobile viewport test (375px)
+
+**For backend stories:**
+- Write unit tests for the business logic
+- Write API tests that validate all endpoints
+- Test error responses (400, 401, 500)
+- Test validation rules
+
+### 2. Implement the Feature
+
+- Write code to make all tests pass
+- Follow existing patterns in the codebase
+- Handle ALL error cases defined in the story
+- Implement loading states for async operations
+
+### 3. Verify It Actually Works
+
+**Do NOT say you're done until:**
+- All unit tests pass
+- All Playwright tests pass
+- You've opened the browser via MCP and visually verified
+- Console has no errors
+- It works on mobile (375px viewport)
+- Error states are handled gracefully
+
+## Rules
+
+1. **Focus**: Implement ONLY the current story. Do not work on other stories.
+2. **Test first**: Write failing tests before implementation when possible.
+3. **Test frequently**: Run tests after each significant change.
+4. **Error handling is required**: Every story defines error cases - implement them all.
+5. **Verification**: Never complete until browser validation passes.
+6. **NEVER edit prd.json**: Do NOT modify `.ralph/prd.json`. Ralph handles story completion automatically after verification. You only write code and tests.
+7. **Update notes**: After completing work, log what you did in `.ralph/progress.txt` including files created/modified and key decisions made. This helps the next session.
+
+## Verification Checklist
+
+Before considering any story complete:
+
+### Code
+- [ ] All acceptance criteria are met
+- [ ] All error handling from story is implemented
+- [ ] Loading states implemented (if frontend)
+- [ ] Validation implemented (if backend)
+- [ ] TypeScript compiles without errors
+
+### Tests
+- [ ] Unit tests written and passing
+- [ ] Playwright test written and passing (frontend)
+- [ ] API tests written and passing (backend)
+- [ ] Error cases tested
+- [ ] Edge cases tested (empty state, etc.)
+
+### Browser/API Validation
+- [ ] Browser check passes (frontend) - no console errors
+- [ ] Mobile viewport works (375px)
+- [ ] Accessibility passes (can Tab through, focus visible)
+- [ ] API returns correct responses (backend)
+
+### Documentation
+- [ ] Updated `.ralph/progress.txt` with files created/modified
+- [ ] Noted any key decisions or context for next story
+
+### Quality
+- [ ] Linting passes
+- [ ] Existing tests still pass
+
+## If Verification Fails
+
+If any check fails:
+1. Read the error message carefully
+2. Fix the issue
+3. Re-run verification
+4. Iterate until ALL checks pass
+
+Do NOT give up. Keep iterating until it works.
+
+## If Blocked
+
+If you encounter a blocker you cannot resolve:
+1. Document the issue in `.ralph/progress.txt`
+2. Note what you tried and why it didn't work
+3. Suggest potential solutions for the next session
+4. Do NOT mark the story as passing
+
+## Code Quality Standards
+
+### Core Principles
+- **Readability First**: Code is read more than written. Prioritize clarity.
+- **KISS**: Keep it simple. Avoid over-engineering.
+- **DRY**: Don't repeat yourself. Extract reusable logic.
+- **YAGNI**: Don't build features you don't need yet.
+
+### Naming Conventions
+- Variables: descriptive camelCase (`userProfile`, `isLoading`, `marketSearchQuery`)
+- Functions: verb-noun pattern (`fetchUserData`, `validateInput`, `handleSubmit`)
+- Components: PascalCase (`UserProfile`, `MarketCard`)
+- Constants: SCREAMING_SNAKE_CASE (`MAX_RETRIES`, `API_BASE_URL`)
+
+### Immutability (CRITICAL)
+Always use spread operators. Never mutate directly:
+```typescript
+// ❌ Bad - mutation
+user.name = 'new name';
+items.push(newItem);
+
+// ✅ Good - immutable
+const updatedUser = { ...user, name: 'new name' };
+const updatedItems = [...items, newItem];
+```
+
+### Error Handling
+Every async operation needs proper error handling:
+```typescript
+// ✅ Good
+try {
+  const data = await fetchData();
+  return { success: true, data };
+} catch (error) {
+  console.error('Failed to fetch data:', error);
+  return { success: false, error: error.message };
+}
+```
+
+### Type Safety
+- Use TypeScript interfaces for all data shapes
+- Never use `any` - use `unknown` if type is truly unknown
+- Define return types for functions
+
+### Functions
+- Max 50 lines per function (split if longer)
+- Single responsibility - one function does one thing
+- Early returns for guard clauses
+
+### React Specific
+- Functional components with typed props
+- Custom hooks for reusable stateful logic
+- Use `prev =>` for state updates that depend on previous state
+- Avoid excessive ternaries - extract to variables or early returns
+
+### General
+- Follow existing code patterns in the codebase
+- Handle ALL error cases defined in the story
+- Implement loading states for async operations
+- Use meaningful variable and function names
+- Add data-testid attributes for Playwright
+
+## Architecture Rules
+
+- **Put files in the right place**: Follow the directories specified in the PRD
+- **Reuse existing code**: Check for existing components/utils before creating new ones
+- **Don't duplicate**: If something exists, import and use it
+- **Max 300 lines per file**: Split large files into smaller, focused modules
+- **Scripts in scripts/**: Shell scripts and CLI tools go in scripts/ or bin/
+- **Docs in docs/**: Documentation files go in docs/
+- **Single responsibility**: Each file/function does one thing well
+
+## Scalability Rules
+
+For list/query endpoints:
+- **Always paginate**: Never return unbounded arrays
+- **Use cursor-based pagination**: When specified in the PRD
+- **Add database indexes**: For frequently queried fields
+- **Implement caching**: As specified in the PRD (TTL, invalidation)
+- **Eager load relationships**: To avoid N+1 queries
+
+For all endpoints:
+- **Rate limit public endpoints**: As specified in the PRD
+- **Set sensible limits**: Max page size, max request body size
+- **Batch operations**: Use bulk inserts when creating many records
+
+## AI/LLM Configuration
+
+**NEVER hardcode AI model names, API keys, or endpoints.** Always use environment variables or settings.
+
+```python
+# ❌ Bad - hardcoded model
+model = "gpt-4"
+client = OpenAI(api_key="sk-...")
+
+# ✅ Good - from environment/settings
+model = os.environ.get("OPENAI_MODEL", "gpt-4")
+client = OpenAI()  # Uses OPENAI_API_KEY env var
+```
+
+```python
+# ❌ Bad - hardcoded in code
+response = openai.chat.completions.create(
+    model="gpt-4-turbo",
+    max_tokens=4096,
+)
+
+# ✅ Good - from settings/config
+from django.conf import settings
+response = openai.chat.completions.create(
+    model=settings.AI_MODEL,
+    max_tokens=settings.AI_MAX_TOKENS,
+)
+```
+
+If the project has an AI gateway or wrapper, use it:
+```python
+# ✅ Best - use project's AI abstraction
+from myapp.ai import get_completion
+response = get_completion(prompt)
+```
+
+---
+
+## Current Story
+
+(Story details will be injected below by ralph.sh)

package/templates/config/fullstack.json

@@ -0,0 +1,86 @@
+{
+  "auth": {
+    "testUser": "",
+    "testPassword": "",
+    "loginEndpoint": "/api/auth/login",
+    "loginMethod": "POST",
+    "tokenType": "session",
+    "tokenHeader": "Authorization",
+    "tokenPrefix": "Bearer"
+  },
+
+  "docker": {
+    "enabled": false,
+    "composeFile": "docker-compose.yml",
+    "serviceName": "web",
+    "execPrefix": "docker compose exec -T"
+  },
+
+  "paths": {
+    "frontend": "frontend",
+    "backend": ".",
+    "tests": "tests",
+    "e2e": "frontend/tests/e2e"
+  },
+
+  "commands": {
+    "devFrontend": "cd frontend && npm run dev",
+    "devBackend": "python manage.py runserver",
+    "install": "npm install && pip install -r requirements.txt",
+    "seed": "",
+    "resetDb": ""
+  },
+
+  "migrations": {
+    "command": "python manage.py migrate",
+    "pattern": "migrations/.*\\.py$"
+  },
+
+  "checks": {
+    "typescript": "cd frontend && npx tsc --noEmit",
+    "lint": "ruff check .",
+    "lintFrontend": "cd frontend && npm run lint",
+    "test": "python manage.py test --keepdb --parallel",
+    "testFrontend": "cd frontend && npm test"
+  },
+
+  "api": {
+    "baseUrl": "http://localhost:8000",
+    "healthEndpoint": "/api/health",
+    "timeout": 30
+  },
+
+  "playwright": {
+    "enabled": true,
+    "testDir": "frontend/tests/e2e",
+    "projects": ["chromium", "mobile"],
+    "baseUrl": "http://localhost:3000"
+  },
+
+  "verification": {
+    "codeReviewEnabled": true,
+    "browserEnabled": true,
+    "a11yEnabled": true,
+    "mobileViewport": 375,
+    "screenshotOnFailure": true
+  },
+
+  "urls": {
+    "frontend": "http://localhost:3000",
+    "backend": "http://localhost:8000",
+    "docs": "http://localhost:8000/api/docs"
+  },
+
+  "env": {
+    "required": ["DATABASE_URL", "SECRET_KEY"],
+    "optional": ["REDIS_URL", "SENTRY_DSN"]
+  },
+
+  "maxIterations": 20,
+  "maxSessionSeconds": 600,
+
+  "contextRotThreshold": {
+    "maxStories": 10,
+    "maxFilesChanged": 20
+  }
+}

package/templates/config/go.json

@@ -0,0 +1,81 @@
+{
+  "auth": {
+    "testUser": "",
+    "testPassword": "",
+    "loginEndpoint": "/api/auth/login",
+    "loginMethod": "POST",
+    "tokenType": "jwt",
+    "tokenHeader": "Authorization",
+    "tokenPrefix": "Bearer"
+  },
+
+  "docker": {
+    "enabled": false,
+    "composeFile": "docker-compose.yml",
+    "serviceName": "app",
+    "execPrefix": "docker compose exec -T"
+  },
+
+  "paths": {
+    "src": ".",
+    "tests": ".",
+    "e2e": "tests/e2e"
+  },
+
+  "commands": {
+    "dev": "go run .",
+    "install": "go mod download",
+    "seed": "",
+    "resetDb": ""
+  },
+
+  "migrations": {
+    "command": "migrate -path migrations -database $DATABASE_URL up",
+    "pattern": "migrations/.*\\.sql$"
+  },
+
+  "checks": {
+    "build": "go build ./...",
+    "lint": "golangci-lint run",
+    "test": "go test ./..."
+  },
+
+  "api": {
+    "baseUrl": "http://localhost:8080",
+    "healthEndpoint": "/health",
+    "timeout": 30
+  },
+
+  "playwright": {
+    "enabled": false,
+    "testDir": "tests/e2e",
+    "projects": ["chromium"],
+    "baseUrl": "http://localhost:8080"
+  },
+
+  "verification": {
+    "codeReviewEnabled": true,
+    "browserEnabled": true,
+    "a11yEnabled": false,
+    "mobileViewport": 375,
+    "screenshotOnFailure": true
+  },
+
+  "urls": {
+    "app": "http://localhost:8080",
+    "docs": "http://localhost:8080/swagger"
+  },
+
+  "env": {
+    "required": ["DATABASE_URL"],
+    "optional": ["REDIS_URL"]
+  },
+
+  "maxIterations": 20,
+  "maxSessionSeconds": 600,
+
+  "contextRotThreshold": {
+    "maxStories": 10,
+    "maxFilesChanged": 20
+  }
+}

package/templates/config/minimal.json

@@ -0,0 +1,76 @@
+{
+  "auth": {
+    "testUser": "",
+    "testPassword": "",
+    "loginEndpoint": "/api/auth/login",
+    "loginMethod": "POST",
+    "tokenType": "session",
+    "tokenHeader": "Authorization",
+    "tokenPrefix": "Bearer"
+  },
+
+  "docker": {
+    "enabled": false,
+    "composeFile": "docker-compose.yml",
+    "serviceName": "app",
+    "execPrefix": "docker compose exec -T"
+  },
+
+  "paths": {
+    "src": "src",
+    "tests": "tests",
+    "e2e": "tests/e2e"
+  },
+
+  "commands": {
+    "dev": "",
+    "install": "",
+    "seed": "",
+    "resetDb": ""
+  },
+
+  "migrations": {
+    "command": "",
+    "pattern": ""
+  },
+
+  "checks": {},
+
+  "api": {
+    "baseUrl": "http://localhost:3000",
+    "healthEndpoint": "/health",
+    "timeout": 30
+  },
+
+  "playwright": {
+    "enabled": false,
+    "testDir": "tests/e2e",
+    "projects": ["chromium"],
+    "baseUrl": "http://localhost:3000"
+  },
+
+  "verification": {
+    "codeReviewEnabled": false,
+    "browserEnabled": false,
+    "a11yEnabled": false,
+    "mobileViewport": 375,
+    "screenshotOnFailure": false
+  },
+
+  "urls": {
+    "app": "http://localhost:3000"
+  },
+
+  "env": {
+    "required": [],
+    "optional": []
+  },
+
+  "maxIterations": 20,
+  "maxSessionSeconds": 600,
+
+  "contextRotThreshold": {
+    "maxStories": 10,
+    "maxFilesChanged": 20
+  }
+}

package/templates/config/node.json

@@ -0,0 +1,81 @@
+{
+  "auth": {
+    "testUser": "",
+    "testPassword": "",
+    "loginEndpoint": "/api/auth/login",
+    "loginMethod": "POST",
+    "tokenType": "jwt",
+    "tokenHeader": "Authorization",
+    "tokenPrefix": "Bearer"
+  },
+
+  "docker": {
+    "enabled": false,
+    "composeFile": "docker-compose.yml",
+    "serviceName": "app",
+    "execPrefix": "docker compose exec -T"
+  },
+
+  "paths": {
+    "src": "src",
+    "tests": "tests",
+    "e2e": "tests/e2e"
+  },
+
+  "commands": {
+    "dev": "npm run dev",
+    "install": "npm install",
+    "seed": "",
+    "resetDb": ""
+  },
+
+  "migrations": {
+    "command": "npx prisma migrate deploy",
+    "pattern": "prisma/migrations/.*"
+  },
+
+  "checks": {
+    "typescript": "npx tsc --noEmit",
+    "lint": "npm run lint",
+    "test": "npm test"
+  },
+
+  "api": {
+    "baseUrl": "http://localhost:3000",
+    "healthEndpoint": "/api/health",
+    "timeout": 30
+  },
+
+  "playwright": {
+    "enabled": true,
+    "testDir": "tests/e2e",
+    "projects": ["chromium", "mobile"],
+    "baseUrl": "http://localhost:3000"
+  },
+
+  "verification": {
+    "codeReviewEnabled": true,
+    "browserEnabled": true,
+    "a11yEnabled": true,
+    "mobileViewport": 375,
+    "screenshotOnFailure": true
+  },
+
+  "urls": {
+    "app": "http://localhost:3000",
+    "docs": "http://localhost:3000/api/docs"
+  },
+
+  "env": {
+    "required": ["DATABASE_URL"],
+    "optional": ["REDIS_URL", "SENTRY_DSN"]
+  },
+
+  "maxIterations": 20,
+  "maxSessionSeconds": 600,
+
+  "contextRotThreshold": {
+    "maxStories": 10,
+    "maxFilesChanged": 20
+  }
+}

package/templates/config/python.json

@@ -0,0 +1,81 @@
+{
+  "auth": {
+    "testUser": "",
+    "testPassword": "",
+    "loginEndpoint": "/api/auth/login",
+    "loginMethod": "POST",
+    "tokenType": "jwt",
+    "tokenHeader": "Authorization",
+    "tokenPrefix": "Bearer"
+  },
+
+  "docker": {
+    "enabled": false,
+    "composeFile": "docker-compose.yml",
+    "serviceName": "app",
+    "execPrefix": "docker compose exec -T"
+  },
+
+  "paths": {
+    "src": "src",
+    "tests": "tests",
+    "e2e": "tests/e2e"
+  },
+
+  "commands": {
+    "dev": "uvicorn main:app --reload",
+    "install": "pip install -r requirements.txt",
+    "seed": "",
+    "resetDb": ""
+  },
+
+  "migrations": {
+    "command": "alembic upgrade head",
+    "pattern": "alembic/versions/.*\\.py$"
+  },
+
+  "checks": {
+    "lint": "ruff check .",
+    "typecheck": "mypy .",
+    "test": "pytest"
+  },
+
+  "api": {
+    "baseUrl": "http://localhost:8000",
+    "healthEndpoint": "/api/health",
+    "timeout": 30
+  },
+
+  "playwright": {
+    "enabled": false,
+    "testDir": "tests/e2e",
+    "projects": ["chromium"],
+    "baseUrl": "http://localhost:8000"
+  },
+
+  "verification": {
+    "codeReviewEnabled": true,
+    "browserEnabled": true,
+    "a11yEnabled": false,
+    "mobileViewport": 375,
+    "screenshotOnFailure": true
+  },
+
+  "urls": {
+    "app": "http://localhost:8000",
+    "docs": "http://localhost:8000/docs"
+  },
+
+  "env": {
+    "required": ["DATABASE_URL"],
+    "optional": ["REDIS_URL", "SENTRY_DSN"]
+  },
+
+  "maxIterations": 20,
+  "maxSessionSeconds": 600,
+
+  "contextRotThreshold": {
+    "maxStories": 10,
+    "maxFilesChanged": 20
+  }
+}