agentic-loop 3.4.6 → 3.5.1

package/templates/PROMPT.md

@@ -1,234 +1,186 @@
-# Development Session
+# Ralph Autonomous Loop
 
-You are an autonomous coding agent working on a feature using the Ralph workflow.
+You're implementing a story from `.ralph/prd.json`. This file contains everything you need.
 
-## 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. Implement the Feature
-
-- Follow existing patterns in the codebase
-- Handle ALL error cases defined in the story
-- Implement loading states for async operations
-
-### 2. Write Tests
-
-**Every new code file MUST have a corresponding test file.**
-
-For **Python** backend stories:
-- New file `foo.py` → create `tests/test_foo.py`
-- Test each public function/method
-- Test error cases (invalid input, missing data, API failures)
-- Test edge cases (empty lists, None values, boundary conditions)
-- Use pytest fixtures for database/API mocking
-
-For **Go** projects:
-- New file `foo.go` → create `foo_test.go` in same directory
-- Use table-driven tests for multiple cases
-- Test error paths and edge cases
-
-For **frontend** stories (TypeScript/React):
-- New component `Foo.tsx` → create `Foo.test.tsx`
-- Test rendering, user interactions, error states
-- Test loading states and empty states
+---
 
-**Do NOT skip tests.** If test enforcement is enabled, verification will fail without tests.
+## Step 1: Orient (MANDATORY)
 
-### 3. Verify It Actually Works
+Before writing any code, run these commands:
 
-**You have browser tools - USE THEM to verify your work:**
+```bash
+git log --oneline -5                    # Recent commits
+cat .ralph/progress.txt | tail -30      # Recent activity
+```
 
-**Playwright MCP** (testing & automation):
-- Navigate to URLs and verify page content
-- Take screenshots to verify UI renders correctly
-- Click elements and fill forms to test interactions
-- Get accessibility snapshots for a11y testing
+Then read these files:
+- `.ralph/prd.json` - Find your story, note `techStack`, `globalConstraints`
+- `CLAUDE.md` - Project conventions and coding standards
+- Files listed in `story.contextFiles[]` - Idea files, styleguides, ASCII mockups
+- `~/.claude/DNA.md` - Personal coding preferences (if exists)
 
-**Chrome DevTools MCP** (debugging & inspection):
-- Inspect DOM elements and check console for errors
-- Debug network requests and responses
-- Check element styles and computed properties
+---
 
-**Do NOT say you're done until:**
-- All unit tests pass
-- You've opened the browser and visually verified the feature works
-- Console has no errors
-- Error states are handled gracefully
+## Step 2: Check for Failures
 
-## Rules
+If `.ralph/last_failure.txt` exists, read it carefully. Understand what went wrong. Don't repeat that mistake.
 
-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
+## Step 3: Read Learned Patterns
 
-Before considering any story complete:
+Read `.ralph/signs.json` - these are patterns learned from past failures. Follow them strictly.
 
-- [ ] All acceptance criteria are met
-- [ ] All error handling from story is implemented
-- [ ] TypeScript/code compiles without errors
-- [ ] Unit tests written and passing
-- [ ] **Browser verified** - used Playwright MCP to visually confirm it works
-- [ ] No console errors
-- [ ] Linting passes
-- [ ] Updated `.ralph/progress.txt` with files created/modified
+---
 
-## If Verification Fails
+## Step 4: Verify Prerequisites
 
-If any check fails:
-1. Read the error message carefully
-2. Fix the issue
-3. Re-run verification
-4. Iterate until ALL checks pass
+Check `story.prerequisites[]` in your story. Ensure:
+- Required servers are running (check `.ralph/config.json` for URLs)
+- Database is seeded if needed
+- Dependencies are installed
 
-Do NOT give up. Keep iterating until it works.
+---
 
-## If Blocked
+## Step 5: Implement
 
-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
+Work on your story following these rules:
 
-## Code Quality Standards
+### From Your Story
+- **story.acceptanceCriteria** - What must be true when done
+- **story.files** - Which files to create, modify, reuse (don't touch others)
+- **story.testing** - Test types, approach (TDD/test-after), and test files to create
+- **story.errorHandling** - How to handle failures
+- **story.apiContract** - Expected request/response format (if applicable)
+- **story.notes** - Human guidance and preferences
+- **story.skills** - Read `.claude/commands/{skill}.md` for patterns
 
-### 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.
+### From the PRD
+- **prd.globalConstraints** - Rules that apply to ALL stories
+- **prd.testing** - Testing strategy (TDD, tools, coverage)
 
-### 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`)
+### From Config (.ralph/config.json)
+- **config.urls.backend** - API base URL for curl tests
+- **config.urls.frontend** - Frontend URL for browser tests
+- **config.directories** - Where frontend/backend code lives
 
-### Immutability (CRITICAL)
-Always use spread operators. Never mutate directly:
-```typescript
-// ❌ Bad - mutation
-user.name = 'new name';
-items.push(newItem);
+### Code Quality
+- **Readability First** - Code is read more than written
+- **KISS** - Keep it simple, avoid over-engineering
+- **DRY** - Don't repeat yourself
+- **YAGNI** - Don't build features you don't need yet
 
-// ✅ Good - immutable
-const updatedUser = { ...user, name: 'new name' };
-const updatedItems = [...items, newItem];
-```
+### Removing UI? Update Tests!
+When removing or modifying UI elements:
+1. `grep -r "element text or testid" tests/` to find related tests
+2. Update or remove tests that reference removed elements
+3. Verify with: `grep -r "removed text" tests/ && exit 1 || echo "clean"`
 
 ### 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);
+  console.error('Failed to fetch:', 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
-```
+### Testing (Follow story.testing)
 
-```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,
-)
-```
+**Check `story.testing.approach`:**
+- **TDD**: Write failing test FIRST, then implement to make it pass
+- **test-after**: Implement first, then write tests
 
-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)
+**Test Types** (from `story.testing.types`):
+| Type | What to Test |
+|------|--------------|
+| `unit` | Individual functions/components in isolation |
+| `integration` | How pieces work together (API + DB, Component + Hook) |
+| `e2e` | Full user flows in browser |
+
+**Test Files** (from `story.testing.files`):
+Create the exact test files specified in the story.
+
+**TDD Workflow:**
+```
+1. Write test for first acceptance criterion → FAIL
+2. Write minimum code to pass → PASS
+3. Refactor if needed
+4. Repeat for next criterion
 ```
 
 ---
 
+## Step 6: Verify
+
+### Run Test Steps
+Execute each command in `story.testSteps[]`. All must pass.
+
+### Browser Verification (if story.mcp includes browser tools)
+Use the MCP tools specified in `story.mcp[]`:
+
+**Playwright MCP** (`playwright`):
+- Navigate to `story.testUrl`
+- Take screenshots to verify UI
+- Click elements and fill forms
+- Check accessibility
+
+**Chrome DevTools MCP** (`devtools`):
+- Check console for errors
+- Inspect network requests
+- Debug DOM issues
+
+**Do NOT mark complete until:**
+- All test steps pass
+- Browser verification confirms it works
+- Console has no errors
+
+---
+
+## Step 7: End Clean
+
+After completing the story:
+
+1. **Update progress notes**
+   ```bash
+   echo "$(date): Completed TASK-XXX - [brief summary]" >> .ralph/progress.txt
+   ```
+
+2. **Note files changed**
+   - List files created/modified in progress.txt
+   - Note any key decisions made
+
+3. **Leave code ready for commit**
+   - No console.log or debug statements
+   - No commented-out code
+   - All tests passing
+
+---
+
+## Rules
+
+1. **Focus** - Implement ONLY the current story
+2. **Follow the PRD** - It has all the context you need
+3. **Read before coding** - Understand existing patterns first
+4. **Test frequently** - Run tests after each significant change
+5. **NEVER edit prd.json** - Ralph handles story completion
+6. **Don't give up** - If verification fails, fix and retry
+
+---
+
+## 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
+4. Do NOT mark the story as passing
+
+---
+
 ## Current Story
 
-(Story details will be injected below by ralph.sh)
+(Story ID will be provided below - read full details from .ralph/prd.json)

package/templates/config/fullstack.json

@@ -16,7 +16,7 @@
     "execPrefix": "docker compose exec -T"
   },
 
-  "paths": {
+  "directories": {
     "frontend": "frontend",
     "backend": ".",
     "tests": "tests",

package/templates/examples/CLAUDE-fullstack.md

@@ -19,8 +19,9 @@
 - **Constants**: `SCREAMING_SNAKE` — e.g., `MAX_RETRIES`
 
 ## Tech Stack
-- **Frontend**: React 18, TypeScript, Vite, TailwindCSS
-- **Backend**: Django 5, Django REST Framework
+<!-- Customize these for your project - detect from package.json/pyproject.toml -->
+- **Frontend**: React, TypeScript, Vite, TailwindCSS
+- **Backend**: Django, Django REST Framework
 - **Database**: PostgreSQL
 - **Cache/Queue**: Redis, Celery
 - **Testing**: pytest (backend), Vitest (frontend), Playwright (E2E)

package/templates/examples/CLAUDE-node.md

@@ -9,7 +9,8 @@
 - **API endpoints**: `kebab-case` — e.g., `/api/user-profile`, `/api/auth/sign-in`
 
 ## Tech Stack
-- **Runtime**: Node.js 20+
+<!-- Customize these for your project - detect from package.json -->
+- **Runtime**: Node.js
 - **Framework**: Express.js / Fastify
 - **Language**: TypeScript
 - **Database**: PostgreSQL with Prisma

package/templates/examples/CLAUDE-react.md

@@ -10,7 +10,8 @@
 - **CSS classes**: `kebab-case` (TailwindCSS utility classes are standard)
 
 ## Tech Stack
-- **Frontend**: React 18, TypeScript, Vite
+<!-- Customize these for your project - detect from package.json -->
+- **Frontend**: React, TypeScript, Vite
 - **Styling**: TailwindCSS
 - **State**: React Query for server state, Zustand for client state
 - **Testing**: Vitest, React Testing Library, Playwright

package/templates/github/workflows/nightly.yml

@@ -1,97 +1,34 @@
 # Nightly comprehensive test suite
-# Runs full tests + all PRD testSteps
+# This is a minimal template. Run `npx agentic-loop ci install` to generate
+# a workflow customized for your project structure.
 
 name: Nightly Tests
 
 on:
   schedule:
-    # Run at 3am UTC every day
-    - cron: '0 3 * * *'
-  workflow_dispatch: # Allow manual trigger
+    - cron: '0 3 * * *'  # 3am UTC daily
+  workflow_dispatch:
 
 jobs:
   test:
     runs-on: ubuntu-latest
-
-    services:
-      # Add postgres if your project needs it
-      postgres:
-        image: postgres:15
-        env:
-          POSTGRES_USER: test
-          POSTGRES_PASSWORD: test
-          POSTGRES_DB: test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-    env:
-      DATABASE_URL: postgresql://test:test@localhost:5432/test
-
     steps:
       - uses: actions/checkout@v4
 
-      # Python setup
-      - name: Set up Python
-        if: hashFiles('pyproject.toml') != '' || hashFiles('requirements.txt') != ''
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - name: Install Python dependencies
-        if: hashFiles('pyproject.toml') != ''
-        run: |
-          pip install uv
-          uv pip install -e ".[dev]" --system 2>/dev/null || pip install -e ".[dev]" 2>/dev/null || pip install -e . 2>/dev/null || true
-
-      # Node.js setup
       - name: Set up Node.js
-        if: hashFiles('package.json') != ''
         uses: actions/setup-node@v4
         with:
           node-version: '20'
-          cache: 'npm'
 
-      - name: Install Node dependencies
-        if: hashFiles('package.json') != ''
-        run: npm ci
+      - name: Install dependencies
+        run: npm ci 2>/dev/null || true
 
-      # Run database migrations if needed
-      - name: Run migrations
-        if: hashFiles('alembic.ini') != ''
-        run: alembic upgrade head
-        continue-on-error: true
-
-      # Python tests
-      - name: Python tests
-        if: hashFiles('pyproject.toml') != '' || hashFiles('pytest.ini') != ''
-        run: |
-          pytest -v --tb=short 2>/dev/null || python -m pytest -v --tb=short 2>/dev/null || true
-
-      # Node tests
-      - name: Node tests
-        if: hashFiles('package.json') != ''
+      - name: Run tests
         run: npm test 2>/dev/null || true
 
-      # PRD testSteps (if ralph is set up)
-      - name: Install ralph
-        run: npm install -g agentic-loop 2>/dev/null || true
-
       - name: Run PRD tests
         if: hashFiles('.ralph/prd.json') != ''
-        run: ralph test prd 2>/dev/null || true
-        continue-on-error: true
-
-      # Coverage report
-      - name: Coverage report
-        if: hashFiles('pyproject.toml') != ''
-        run: |
-          pip install pytest-cov
-          pytest --cov --cov-report=term-missing 2>/dev/null || true
+        run: npx agentic-loop test prd 2>/dev/null || true
         continue-on-error: true
 
   notify:
@@ -100,6 +37,4 @@ jobs:
     if: failure()
     steps:
       - name: Notify on failure
-        run: |
-          echo "Nightly tests failed! Check the workflow run for details."
-          # Add Slack/Discord notification here if desired
+        run: echo "Nightly tests failed!"

package/templates/github/workflows/pr.yml

@@ -1,5 +1,6 @@
 # Fast PR checks - lint only, no tests
-# Tests run in nightly workflow to keep PRs fast
+# This is a minimal template. Run `npx agentic-loop ci install` to generate
+# a workflow customized for your project structure.
 
 name: PR Check
 
@@ -13,44 +14,19 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      # Python linting
-      - name: Set up Python
-        if: hashFiles('pyproject.toml') != '' || hashFiles('requirements.txt') != ''
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - name: Install Python dependencies
-        if: hashFiles('pyproject.toml') != ''
-        run: |
-          pip install ruff
-          pip install -e . 2>/dev/null || true
-
-      - name: Ruff lint
-        if: hashFiles('pyproject.toml') != '' || hashFiles('ruff.toml') != ''
-        run: ruff check .
-
-      # Node.js linting
       - name: Set up Node.js
-        if: hashFiles('package.json') != ''
         uses: actions/setup-node@v4
         with:
           node-version: '20'
-          cache: 'npm'
 
-      - name: Install Node dependencies
-        if: hashFiles('package.json') != ''
-        run: npm ci
+      - name: Install dependencies
+        run: npm ci 2>/dev/null || true
 
-      - name: ESLint
-        if: hashFiles('package.json') != ''
-        run: npm run lint 2>/dev/null || npx eslint . 2>/dev/null || true
+      - name: Lint
+        run: npm run lint 2>/dev/null || true
 
       - name: TypeScript check
-        if: hashFiles('tsconfig.json') != ''
-        run: npx tsc --noEmit
+        run: npx tsc --noEmit 2>/dev/null || true
 
-      # Build check (catches import/bundling errors)
       - name: Build
-        if: hashFiles('package.json') != ''
         run: npm run build 2>/dev/null || true

package/templates/signs.json

@@ -41,6 +41,13 @@
       "category": "frontend",
       "learnedFrom": null,
       "createdAt": "2026-01-20T00:00:00-08:00"
+    },
+    {
+      "id": "sign-007",
+      "pattern": "When removing or modifying UI elements, grep for related tests and update them - stale tests that check for removed elements will fail",
+      "category": "testing",
+      "learnedFrom": null,
+      "createdAt": "2026-01-25T00:00:00-08:00"
     }
   ]
 }