Build Phase

You are implementing a feature for Orcha, a Clojure document processing platform.

Your Task

1. Read IMPLEMENTATION_PLAN.md in the workspace root
2. Find the first pending task (marked [ ])
3. Implement ONLY that task
4. Verify and commit the changes
5. Output CONTINUE (or completion marker if done)

Before You Start

Read these files:

• CLAUDE.md - Project code style and conventions
• .ralph/AGENTS.md - Build, test, and validation commands
• .ralph/guardrails.md - Failure patterns to avoid
• IMPLEMENTATION_PLAN.md - The implementation plan

Implementation Workflow

1. Read Before Write

Always read files before editing. Understand existing patterns.

2. Make Changes

Follow the code style from CLAUDE.md:

• Kebab-case for Clojure identifiers
• ^:private for non-public functions
• Two blank lines between top-level forms
• Requires ordered alphabetically
• Inline single-use logic

3. Verify Changes

Always compile-check after editing Clojure files:

clojure -M -e "(require 'the.namespace :reload)"

Lint check:

clj-kondo --lint src test --fail-level warning

4. Testing Strategy

Tests are slow (~8 min). Use this tiered approach:

Low-risk changes (compile-check only)

• Config files (config.edn)
• New namespaces with no dependencies yet
• Schema definitions
• Pure functions without side effects
• Documentation strings

High-risk changes (run selective tests)

• Database queries → run related *_test.clj
• API handlers → run related *_test.clj
• Middleware changes → run middleware tests
• Changes to existing functions with tests

Run selective tests:

# Map source ns to test ns: com.getorcha.foo → com.getorcha.foo-test
clj -X:test :nses '[com.getorcha.foo-test]' 2>&1 | grep -E "(FAIL in|ERROR in|Execution error|failed because)"

Phase completion (run full test suite)

When completing the last task of a phase, run the full test suite:

clj -X:test 2>&1 | grep -E "(FAIL in|ERROR in|Execution error|failed because)"

If tests fail at phase end:

1. Identify which task broke tests
2. Fix the issue
3. Commit the fix
4. Re-run full tests before proceeding to next phase

5. Commit

Stage specific files (NEVER use git add -A or git add .):

git add path/to/specific/file.clj
git commit -m "Description of change"

6. Update Plan

Mark the completed task in IMPLEMENTATION_PLAN.md:

- [x] Task 1: Description

7. Output

If more tasks remain:

CONTINUE

If all tasks are complete, read .ralph/completion-marker.txt and output its contents.

Determining Phase Boundaries

Look at the ## Tasks section in IMPLEMENTATION_PLAN.md. Phases are marked with headers like:

### Phase 1: Configuration & Foundation
### Phase 2: OAuth Library

The last task before the next ### Phase header (or end of tasks) is the phase-end task.

Database Access

• PostgreSQL: psql -c "SELECT ..."
• Tables use snake_case, results come back as kebab-case qualified keywords

AWS Services

• LocalStack endpoint: http://localstack:4566
• S3: aws --endpoint-url=http://localstack:4566 s3 ...

Common Patterns

Adding an API endpoint

1. Define route in router namespace
2. Create handler function
3. Add Malli schemas for request/response
4. Add tests

Database queries

(db.sql/execute! pool
  {:select [:*]
   :from [:table-name]
   :where [:= :column value]})

Creating migrations

bb migrate create "migration-name"

Guardrails

• READ_BEFORE_WRITE: Always read files first
• COMPILE_CHECK: Verify compilation after edits
• LINT_CHECK: Run clj-kondo before commit
• SELECTIVE_TESTS: Run relevant tests for high-risk changes
• PHASE_END_TESTS: Full test suite at phase completion
• SPECIFIC_STAGING: Never git add -A
• ONE_TASK_ONLY: One task per iteration
• NO_SECRETS: Never commit credentials