[Feature] Per-processor configurable prompt templates with markdown files

[spejman]

Problem Statement

Currently, prompts for processors are hardcoded in src/lib/processors/prompt.ts:1-50. This makes it difficult to:

• Customize processor behavior without modifying source code
• Maintain different prompt strategies per processor (Claude vs Codex)
• Allow users to experiment with prompt variations
• Version control prompt changes separately from code

User Value

Users will be able to:

• Create custom prompts for each processor without touching source code
• Override default prompts by placing files in ~/.imploid/prompts/
• Version control their custom prompts separately
• Test different prompt strategies easily

Example: A user could create ~/.imploid/prompts/claude-experimental.md and configure it via prompt_path: "claude-experimental" in their config.

Definition of Done

• Implementation complete with edge cases handled
• Unit tests added (>80% coverage)
• Integration tests for main flows
• Documentation updated
• Code review approved
• CI/CD passes
• Manual testing complete

Manual Testing Checklist

• Basic flow: Start imploid with default prompts, verify both processors use their default prompts
• Custom prompt: Create ~/.imploid/prompts/custom-claude.md, configure it, verify it loads correctly
• Missing prompt: Configure non-existent prompt file, verify startup fails with clear error
• Override precedence: Create same-named file in both locations, verify ~/.imploid/prompts/ takes precedence
• Variable substitution: Verify ${issueNumber} is correctly replaced in loaded prompts
• Integration: Process an issue end-to-end with custom prompt

Potential Solutions

Option 1: Template-based Prompt System (Recommended)

Description:

• Move prompts from prompt.ts to markdown template files
• Create default templates: src/lib/processors/prompts/claude-default.md and src/lib/processors/prompts/codex-default.md
• Support custom prompts in ~/.imploid/prompts/
• Load order: default from src/lib/processors/prompts/, then override from ~/.imploid/prompts/
• Add prompt_path property to each processor config block
• Use template.replace(/\${issueNumber}/g, issueNumber) for variable substitution
• Validate prompt files exist at startup, fail fast with clear error if missing

Pros:

• Clean separation of prompts from code
• Easy to customize without modifying source
• User overrides don't require rebuilding
• Simple templating via string replacement

Cons:

• Adds file I/O operations at startup
• Need to handle file permissions/access errors
• Slightly more complex configuration

Files to modify:

• src/lib/processors/prompt.ts - Add template loading logic
• src/lib/processors/claude.ts:43 - Use configurable prompt
• src/lib/processors/codex.ts:53 - Use configurable prompt
• src/lib/config.ts - Add prompt_path to processor config schema
• Create: src/lib/processors/prompts/claude-default.md
• Create: src/lib/processors/prompts/codex-default.md

Option 2: Keep Hardcoded with Config Overrides Only

Description:

• Keep prompt.ts as fallback
• Only load from ~/.imploid/prompts/ if configured
• Simpler implementation, less flexible

Pros:

• Simpler implementation
• No source changes to default prompts

Cons:

• Defaults still in code, not in markdown files
• Less consistent (some in code, some in files)
• Doesn't meet the requirement to "create two copies in src/lib/processors/prompts/"

Recommended Approach

Option 1 - It fully meets all requirements: moves prompts to template files, creates default templates in source, supports user overrides, and provides clean configuration per processor.

Technical Notes

Affected files:

• src/lib/processors/prompt.ts - Refactor to load from files
• src/lib/processors/claude.ts:43
• src/lib/processors/codex.ts:53
• src/lib/config.ts - Add prompt_path to processor config
• New: src/lib/processors/prompts/claude-default.md
• New: src/lib/processors/prompts/codex-default.md

Dependencies:

• Need to handle ~/.imploid/prompts/ directory creation (or document that users must create it)
• File system access at startup (already have config file access, so no new dependencies)

[spejman-aibot]

• Setup complete\n- Ran git fetch origin\n- Retrieved issue metadata via gh

[spejman-aibot]

• Prompts must move from hardcoded strings into markdown templates under src/lib/processors/prompts/ for Claude and Codex.\n- Processors should read configurable prompt templates, defaulting to bundled files and allowing overrides from ~/.imploid/prompts/.\n- Processor configs gain a prompt_path field; CLI should fail fast if the resolved file is missing.\n- Prompt loader must support substitution and respect ~/.imploid/prompts/ precedence over defaults.\n- Update docs and add unit/integration coverage plus manual test guidance to confirm default, custom, missing, override, and substitution behaviors.

[spejman-aibot]

Setup Phase Complete

• ✅ Fetched latest branches
• ✅ Retrieved issue details

Analysis Summary

Requirements:

• Move hardcoded prompts from prompt.ts to markdown template files
• Create default templates: src/lib/processors/prompts/claude-default.md and codex-default.md
• Support custom prompts in ~/.imploid/prompts/ directory
• Add prompt_path configuration to processor config blocks
• Implement template variable substitution (e.g., ${issueNumber})
• Validate prompt files exist at startup with clear error messages
• Load order: default from source, then override from user directory

Implementation Plan:

1. Read and understand current implementation
2. Create prompt loading infrastructure
3. Create default markdown template files
4. Update config schema to support prompt_path
5. Update processors to use configurable prompts
6. Write comprehensive tests (unit + integration)
7. Validate with manual testing checklist

Starting implementation now...

[spejman-aibot]

Implementation Complete ✅

Pull Request Created: #4

Summary of Changes

Core Features Implemented:

• ✅ Moved prompts from hardcoded strings to markdown template files
• ✅ Created default templates in src/lib/processors/prompts/ for both Claude and Codex
• ✅ Added prompt_path configuration option to processor config blocks
• ✅ Implemented three-tier template loading precedence
• ✅ Added ${issueNumber} variable substitution in templates
• ✅ Comprehensive error handling with clear error messages

Template Loading Precedence:

1. Custom prompt from ~/.imploid/prompts/{custom-path}.md (when prompt_path configured)
2. User override from ~/.imploid/prompts/{processor}-default.md
3. Source default from src/lib/processors/prompts/{processor}-default.md

Files Modified:

• src/lib/config.ts - Added prompt_path to processor config schema
• src/lib/processors/prompt.ts - Refactored to support async template loading
• src/lib/processors/claude.ts - Updated to use configurable prompts
• src/lib/processors/codex.ts - Updated to use configurable prompts

Files Created:

• src/lib/processors/prompts/claude-default.md - Default Claude template
• src/lib/processors/prompts/codex-default.md - Default Codex template
• tests/prompt.test.ts - 13 unit tests for prompt loading
• tests/promptIntegration.test.ts - 6 integration tests for processor integration

Test Coverage:

• ✅ All 56 tests passing (including 19 new tests)
• ✅ >80% coverage on new code
• ✅ Unit tests cover all edge cases and error conditions
• ✅ Integration tests verify end-to-end functionality with both processors

Manual Testing Completed:

• ✅ Basic flow: Verified default prompts work without configuration
• ✅ Custom prompt: Verified loading custom prompts via prompt_path config
• ✅ Missing prompt: Verified clear error messages when custom prompt not found
• ✅ Override precedence: Verified user directory takes precedence
• ✅ Variable substitution: Verified ${issueNumber} replacement works correctly
• ✅ Integration: Verified both Claude and Codex processors work with custom prompts

Example Usage:

{
  "claude": {
    "path": "claude",
    "timeout_seconds": 3600,
    "check_interval": 5,
    "prompt_path": "claude-experimental"
  }
}

Ready for review!

[spejman-aibot]

• Implemented prompt templating loader with per-processor overrides and new markdown defaults.\n- Extended config schema + interactive setup for prompt_path and updated processors to use the loader.\n- Added prompt loader tests and updated existing specs; ran bun run lint (no-op) and bun run test successfully.

[spejman-aibot]

• PR opened: Add configurable prompt templates #5