Advanced AI-powered image editing orchestration system for consistent, rule-based creative transformations. Converts high-level edit intents into detailed, constraint-aware prompts for generative image models.
# Clone repository
cd ~/agents/creative-director
# Install dependencies
npm install
# Set environment variable
export REPLICATE_API_TOKEN=your_token_here# Run all tests
npm test
# Run specific test file
npm test -- tests/e2e-mock.test.js
# Run with coverage
npm test -- --coverage
# Watch mode for development
npm run devconst { buildPrompt } = require('./src/prompt-builder');
const { assessQuality } = require('./src/quality-assessor');
// Define edit intent
const editIntent = {
targetObject: 'iPhone device mockup',
editType: 'device swap',
sourceType: 'iOS',
targetType: 'Android',
removeMarkers: 'iOS design language',
applyMarkers: 'Material Design 3'
};
// Define constraints
const constraints = {
preserveElements: 'app layout, screen dimensions',
position: 'center of frame',
scale: 'device at 100% scale',
lighting: 'studio lighting at 45 degrees',
interactions: 'all touch targets',
doNotAlter: 'background, photo quality',
doNotIntroduce: 'iOS patterns, Apple branding'
};
// Build prompt
const prompt = buildPrompt(editIntent, constraints);
console.log(prompt.prompt);Creative Director Agent Workflow:
┌─────────────────┐
│ Edit Intent │
│ + Constraints │
└────────┬────────┘
│
v
┌──────────────────────┐
│ Prompt Builder │
│ - Load rules │
│ - Fill variables │
│ - Assemble prompt │
└────────┬─────────────┘
│
v
┌──────────────────────┐
│ Generated Prompt │
│ (12 rules applied) │
└────────┬─────────────┘
│
v
┌──────────────────────┐
│ Quality Assessor │
│ - Validate constraints
│ - Score metrics │
│ - Generate report │
└────────┬─────────────┘
│
v
┌──────────────────────┐
│ Assessment Result │
│ + Success Factors │
│ + Confidence Score │
│ + Concerns │
└──────────────────────┘
- prompt-builder.js - Core orchestration: loads rule templates, fills variable placeholders, assembles complete prompt with all 12 rules
- quality-assessor.js - Quality validation: evaluates constraints, computes confidence scores, identifies success factors and concerns
- replicate-client.js - API integration: sends prompts to Replicate, polls for results, handles retries
- image-handler.js - Image processing: downloads outputs, applies post-processing, validates quality
- orchestrator.js - Workflow engine: coordinates all components, manages state, logs results
- rule-template.json - Rule definitions: 12 editing rules with variable placeholders and descriptions
- utils.js - Helper functions: string manipulation, validation, formatting
- e2e-mock.test.js - End-to-end workflow test: iPhone-to-Android example with full prompt and quality assessment (no API calls)
- prompt-builder.test.js - Unit tests for prompt building logic and rule application
- quality-assessor.test.js - Unit tests for quality assessment and constraint validation
- replicate-client.test.js - Unit tests for API integration
- image-handler.test.js - Unit tests for image processing
- integration.test.js - Multi-component integration tests
- jest.config.js - Jest test runner configuration
- package.json - Dependencies and scripts
- .env - Environment variables (see below)
REPLICATE_API_TOKEN- Replicate API authentication token- Get from: https://replicate.com/account
- Required for image generation workflows
- Not required for testing (uses mocks)
DEBUG- Set totruefor verbose loggingREPLICATE_TIMEOUT- API timeout in seconds (default: 300)LOG_LEVEL- Logging verbosity (debug, info, warn, error)
# From Claude Code conversation
/execute npm test -- tests/e2e-mock.test.js
# Run all tests with coverage
/execute npm test -- --coverage
# Run specific workflow
/execute node src/orchestrator.js# In your Claude Code task
const creative = require('~/agents/creative-director/src/prompt-builder');
const assessment = require('~/agents/creative-director/src/quality-assessor');
// Use functions directly
const result = creative.buildPrompt(intent, constraints);All creative transformations apply these rules consistently:
- Edit Scope Isolation - Confine edits to target object
- Spatial Anchoring - Maintain position and alignment
- Geometry + Optics - Preserve physical proportions
- Lighting + Material Fidelity - Match light and surfaces
- Environmental Interaction - Proper shadow and reflection
- Structural Parity - Maintain hierarchy and layout
- Identity Replacement - Swap design systems cleanly
- Negative Constraints - Eliminate forbidden patterns
- Pixel Fidelity - Maintain image resolution and clarity
- Photorealism - Ensure realistic appearance
- Consistency Pass - Unified style throughout
- Output Quality Threshold - Meet minimum quality standards
- Individual function behavior
- Edge cases and error handling
- Input validation
- Multi-component workflows
- Data flow between modules
- State management
- Complete workflows without external APIs
- Realistic edit scenarios (iPhone-to-Android)
- Quality assessment validation
- Real Replicate integration
- Image generation results
- Error handling
Run mocks only: npm test
Run all tests: npm test -- --testPathIgnorePatterns=integration
- Multi-image workflows - Apply edits to image sequences with consistency
- Version control - Track prompt changes and compare results
- Batch processing - Queue multiple edits with priority management
- Feedback loop - Assess results and auto-refine prompts
- Custom rules - User-defined rules and constraint templates
- Performance analytics - Track metrics across many edits
- Collaborative mode - Share and review edits with team
- Model selection - Support multiple generative models beyond Replicate
The agent is designed for extension:
- Add new rules to
src/rule-template.json - Extend assessor with custom metrics in
src/quality-assessor.js - Integrate additional image models in
src/replicate-client.js - Add preprocessing/postprocessing in
src/image-handler.js
- ESLint configured for consistency
- Follows Airbnb JavaScript style guide
- Strict mode enabled
npm run lint
npm run lint -- --fixEnable verbose logging:
DEBUG=* npm test -- tests/e2e-mock.test.jsWorkflow for changes:
- Create feature branch
- Write tests first (TDD)
- Implement feature
- Run full test suite
- Verify coverage maintained
- Commit with clear message
Builds a complete prompt with all 12 rules applied.
Parameters:
editIntent(object) - What to edit: targetObject, editType, sourceType, targetType, removeMarkers, applyMarkersconstraints(object) - How to edit: preserveElements, position, scale, lighting, interactions, doNotAlter, doNotIntroduce
Returns:
{
prompt: "Complete prompt text with all rules",
rulesApplied: [1, 2, 3, ..., 12],
timestamp: "2026-03-27T10:30:00Z"
}Assesses quality of an edit against constraints.
Parameters:
constraints(object) - Edit constraints and requirementseditIntent(object) - Original and edited content with reasonmetrics(object) - Quality scores (0-100) for grammar, tone, brand_voice, audience, originality, cta_strength, engagement, performance
Returns:
{
meets_constraints: true,
confidence_score: 92,
success_factors: ["Grammar Quality", "Tone Consistency", ...],
concerns: [],
rule_assessments: [
{ruleId: 1, passed: true, reason: "..."},
...
],
timestamp: "2026-03-27T10:30:00Z"
}Q: Can I run tests without API token? A: Yes. Unit and E2E mock tests run without tokens. Integration tests require REPLICATE_API_TOKEN.
Q: How long does a typical edit take? A: Mocked tests <100ms. Real API calls typically 30-60 seconds depending on model queue.
Q: Can I customize the 12 rules? A: Phase 1a uses fixed rules. Phase 2 will support custom rule sets.
Q: What models does this support? A: Phase 1a targets Replicate's image generation APIs. Phase 2 will support additional providers.
Q: How is data stored? A: Results are logged to stdout. Phase 2 will add database persistence.
Proprietary - ARC Internal Use Only
For issues or questions:
- Check existing issues in task tracker
- Review test cases for usage examples
- Consult Phase 1a design doc in project files