@profoundlogic/coderflow-server 0.2.1

package/dist/web-ui/public/docs/tasks/creating-tasks.md

@@ -0,0 +1,111 @@
+# Creating Tasks
+
+A task is a unit of work executed by an AI agent. When you create a task, CoderFlow launches an isolated container, runs the agent with your instructions, and captures the results for your review.
+
+## Tasks vs. Objectives
+
+You can create tasks in two ways:
+
+- **Direct tasks**: Create and launch immediately when you know exactly what needs to be done. Best for simple, well-defined work.
+
+- **Tasks from objectives**: Launch a task from an existing objective. Best when requirements need refinement, work is complex, or you expect multiple iterations. The objective serves as the parent record, tracking all tasks launched from it.
+
+For straightforward fixes or small changes, direct tasks are efficient. For larger initiatives where you'll iterate on requirements, start with an objective and launch tasks from it.
+
+## Writing Instructions
+
+Instructions tell the agent what you want to accomplish. Clear, specific instructions lead to better results.
+
+### Best Practices
+
+- **Be specific**: Instead of "fix the bug," describe the symptom, expected behavior, and relevant files
+- **Include context**: Reference related code, error messages, or test failures
+- **Break down complex work**: Large tasks should be decomposed into logical steps
+- **Specify constraints**: Note performance requirements, style guides, or compatibility needs
+- **Define success criteria**: What does "done" look like? What tests should pass?
+
+### Example
+
+Instead of:
+> "Fix the login issue"
+
+Try:
+> "Users clicking the login button on /auth/login see a spinning loader that never resolves. The expected behavior is a redirect to /dashboard after successful authentication. Check the authentication service for timeout issues—recent logs show 504 errors from the identity provider."
+
+## Attachments
+
+Attach files and screenshots to provide additional context.
+
+### Supported Types
+
+- **Images**: Screenshots, mockups, diagrams (PNG, JPG, GIF, WebP)
+- **Code files**: Source code, configuration, logs
+- **Documents**: Text files, markdown, documentation
+
+Attachments are placed in the container where the agent can access them. Reference attachments in your instructions so the agent knows to use them.
+
+### Adding Attachments
+
+1. Click **Attachments** in the task form
+2. Select files or paste images from your clipboard
+3. Add up to 10 files, 50MB total
+
+Alternatively, drag and drop files directly into the instructions field.
+
+You can also paste screenshots directly into the instructions box using Ctrl+V (Cmd+V on Mac).
+
+## Selecting Agents
+
+Choose which AI agent will work on the task.
+
+### Available Agents
+
+- **Claude**: Strong at complex reasoning and multi-step engineering tasks. Good default for most work.
+- **Codex**: Fast at translating specifications into code. Use for straightforward coding tasks.
+- **Gemini**: Large context window for tasks requiring deep file understanding.
+
+### Running Multiple Agents
+
+Select multiple agents to run the same task in parallel, creating a **task group**. Each agent works independently in its own container. You can then compare their approaches and select the best result.
+
+This is especially powerful for complex tasks where different agents might find different solutions.
+
+## Skills in Tasks
+
+Tasks automatically inherit the skills assigned to the selected environment. Those skills are injected into the task container at launch, so the agent can invoke them immediately.
+
+If a task needs additional skills, update the environment's skill assignments before launching the task.
+
+## Selecting Branches
+
+Whether your environment has one or multiple repositories, you can specify which branch to use for each.
+
+- **Default branch**: Used unless you select another
+- **Branch restrictions**: Some repositories may be locked to specific branches
+- **New branches**: You can create new branches during the approval step
+
+The agent checks out your selected branches before starting work. During approval, you choose whether to push to the same branch, create a new one, or commit without pushing.
+
+## Running the Task
+
+Once you've entered instructions and selected options:
+
+1. Click **Launch Task** (or press Ctrl-Enter)
+2. Task enters the queue if all agent slots are full
+3. Agent starts when a slot is available
+4. Live updates appear in the Activity Feed
+5. Task completes when the agent finishes
+6. Review results and approve, or send follow-up instructions
+
+### Task States
+
+- **Pending**: Created, waiting to be queued
+- **Queued**: Waiting for an available agent slot
+- **Running**: Agent is actively working
+- **Completed**: Agent finished successfully
+- **Failed**: Agent encountered an error
+- **Staged**: Container ready, waiting for you to start the agent
+
+### Queue Management
+
+When all slots are occupied, tasks wait in a first-in-first-out queue. Your position is displayed in the UI. Tasks run automatically when slots open.

package/dist/web-ui/public/docs/tasks/judging.md

@@ -0,0 +1,114 @@
+# Judging
+
+When you run multiple agents on the same task, judge agents can automatically evaluate the results and help you identify the best solution. Judges analyze code quality, correctness, and completeness—providing objective feedback that saves you time reviewing variants.
+
+## What Are Judge Tasks?
+
+A judge task is a special task that evaluates other tasks in a group. Unlike regular tasks that modify your code, judges:
+
+- Run **after** primary tasks complete
+- Have **read-only access** to primary task results
+- Analyze code quality, correctness, and completeness
+- Produce evaluation notes and scoring
+- **Do not modify** your repositories
+
+Judge tasks appear in the task group alongside other variants.
+
+## How Judges Evaluate
+
+When a judge task runs, it:
+
+1. Reads all primary task results—patches, summaries, exit codes, logs
+2. Analyzes the code changes each agent made
+3. Reviews test results and error messages
+4. Evaluates each variant on multiple dimensions
+5. Generates a detailed report with scores and recommendations
+
+### Evaluation Dimensions
+
+Judges score variants on:
+
+- **Correctness**: Does the code solve the problem? Are edge cases handled? Do tests pass?
+- **Code quality**: Is it readable, maintainable, and following good patterns?
+- **Completeness**: Are all requirements addressed? Is anything missing?
+- **Performance**: Is the implementation efficient? (when applicable)
+
+Each dimension receives a score, and judges provide detailed notes explaining their reasoning.
+
+Judges may use or add other dimensions based on the task context.
+
+## Automatic Judging
+
+You can configure task groups to automatically launch judge tasks when primary agents finish.
+
+### Configuring Auto-Judge
+
+When creating a task group, select which agents should serve as judges.
+
+Multiple judges provide independent evaluations, reducing bias and increasing confidence in the results.
+
+### When Auto-Judge Launches
+
+Judge tasks launch automatically when:
+
+- All primary tasks have completed
+- At least two variants finished successfully
+- Multiple variants made file changes
+- No follow-up instructions are pending
+
+If conditions aren't met, auto-judge is skipped—but you can always launch judges manually.
+
+## Manual Judge Launch
+
+You can launch judge tasks at any time:
+
+1. Open the task group
+2. Click the **Judge ucib**
+3. Select which agents to use as judges
+4. Judge tasks are created and queued
+
+This is useful when auto-judge conditions weren't met, or when you want additional evaluation after making changes.
+
+## Judge Consensus
+
+When multiple judges evaluate the same variants:
+
+- Each judge scores independently
+- Results can be compared side-by-side
+- Consensus emerges when judges agree on the best variant
+- Disagreements highlight areas worth closer review
+
+If two out of three judges recommend the same variant, that's a strong signal. If judges disagree significantly, you may want to review their reasoning before deciding.
+
+## Using Judge Feedback
+
+Judge feedback isn't just for picking a winner—it helps you improve the code.
+
+### Common Issues Judges Identify
+
+- **Test failures**: Some tests aren't passing
+- **Edge cases**: Boundary conditions not handled
+- **Error handling**: Missing validation or exception handling
+- **Code style**: Inconsistent naming or formatting
+- **Incomplete implementation**: Features not fully implemented
+
+### Feedback Loops
+
+After reviewing judge feedback:
+
+1. Identify specific issues mentioned in the evaluation
+2. Send follow-up instructions to the winning variant addressing those issues
+3. The agent resumes and implements improvements
+4. Optionally re-run judges to verify the improvements
+
+This creates an automated refinement cycle where judges catch issues that agents then fix.
+
+## Judges Don't Approve
+
+Important: Judge tasks provide **feedback and recommendations only**. They do not:
+
+- Automatically approve changes
+- Commit or push code
+- Mark tasks as winners
+
+You make the final decision on winner selection and approval. Judges inform your decision—they don't make it for you.

package/dist/web-ui/public/docs/tasks/providing-feedback.md

@@ -0,0 +1,41 @@
+# Providing Feedback
+
+After a task starts running, you can provide follow-up instructions to guide the agent toward better results. Feedback helps the agent adjust course, fix errors, or add missing features.
+
+## Follow-Up Instructions (R Hotkey)
+
+The fastest way to send feedback while viewing a task.
+
+### Keyboard Shortcut
+
+Press **R** while viewing a task detail to open the follow-up input under the Latest Update section. Alternatively, use the follow-up box at the bottom of the activity feed.
+
+This works on completed tasks that have an active container. If the container is stopped due to inactivity, you can start it first by clicking the "Start" button.
+
+
+### How Follow-Ups Work
+
+1. Type your feedback in the markdown editor
+2. Paste screenshots or images if needed, attach files, logs, etc.
+3. Press Cmd/Ctrl+Enter or click "Submit"
+4. Agent resumes work, incorporating your feedback, and the status changes back to "running"
+5. View new activity in the feed as the agent processes your instructions
+
+## Using the Feedback Widget
+
+If your environment has an Application Server with Launch URL's enabled, you can use the Testing Menu to launch a copy of your application in a separate browser tab. This runs the application either directly within the container or through a proxy. Both methods support the Feedback widget.
+
+### Widget UI
+
+The feedback widget appears as a floating icon in the corner of your application. Click the icon to open the feedback panel. The panel includes:
+- **Latest Agent Activity Feed** that shows the most recent agent actions that are updated live as the agent runs
+- **Markdown Editor** for formatted feedback, including the ability to paste images and drag/drop attachments
+- **Screenshot Tool** to take annotated screenshots of the application you are running
+- **Element Selector Tool** to provide context-based information by selecting HTML elements on the screen
+- **Context Selection** to send to the agent - DOM, Rich Display data, 5250  buffer data, etc. depending on the application type
+
+## Feedback from Judge Tasks
+
+Judge tasks can identify issues and generate automated feedback for execution tasks. When a completed judge task is selected in the Judge Panel, it may present suggested feedback for the associated execution task along with a severity level.
+
+You can click the **Send as Feedback...** button to send this feedback directly to the execution task. Before the feedback is sent, you have the option to edit or augment it in the markdown editor that appears. Once you confirm, the feedback is submitted, and the execution task will resume work based on the provided instructions.

package/dist/web-ui/public/docs/tasks/task-groups.md

@@ -0,0 +1,73 @@
+# Task Groups & Variants
+
+Task groups let you run the same task with multiple AI agents in parallel, comparing their approaches and selecting the best result.
+
+## What is a Task Group?
+
+A task group is a collection of related tasks that share:
+
+- **Same instructions** and context
+- **Same branch selections** for repositories
+- **Linked visibility** in the UI (see all variants together)
+
+Each task in the group is a **variant**—a different agent's approach to the same problem.
+
+## Creating a Task Group
+
+Groups are created automatically when you submit a task with multiple agents selected. Select Claude, Codex, and Gemini, and you get three variants running in parallel.
+
+You can also add variants to an existing task later (see below).
+
+## Parallel Execution
+
+When your server has multiple queue slots available, variants run simultaneously:
+
+1. All selected agents start at roughly the same time
+2. Each works independently in its own container
+3. Results become available as each agent finishes
+4. You can review completed variants while others are still running
+
+This parallel approach means you get multiple solutions in about the same time it takes to get one.
+
+## Viewing Variants
+
+In the task detail view:
+
+- All variants appear as tabs or panels
+- Each variant shows its own activity feed
+- Switch between variants to see progress, logs, and changes
+- Status indicators show which are running, completed, or failed
+
+## Comparing Variants
+
+Click the comparison view (trophy icon) to see variants side-by-side:
+
+- **Code changes**: Diffs from each agent
+- **Summaries**: What each agent reported doing
+- **Exit status**: Success or failure
+- **Files modified**: Count and list of changes
+
+This view helps you quickly assess which approach looks best before diving into details.
+
+## Adding Agents to Existing Groups
+
+You can add more variants to a completed task:
+
+1. Open the task detail
+2. Click the **Resubmit** icon
+3. Select additional agent(s)
+4. Ensure "Add as variant to existing group" is checked
+5. New variants are created and grouped with the original
+
+This is useful when you want another agent's perspective after seeing initial results, or when you want to try a different agent on a task that didn't produce satisfactory results.
+
+## When to Use Task Groups
+
+Task groups are most valuable when:
+
+- **Uncertain requirements**: Different agents may interpret ambiguous instructions differently
+- **Complex problems**: Multiple approaches might all be valid
+- **Learning agent strengths**: Compare how Claude, Codex, and Gemini handle your codebase
+- **High-stakes changes**: Get multiple opinions before committing
+
+For simple, well-defined tasks, a single agent is often sufficient. Use groups when the extra perspectives are worth the compute time.

package/dist/web-ui/public/docs/tasks/winner-selection.md

@@ -0,0 +1,75 @@
+# Winner Selection
+
+When multiple agents work on the same task, you need to choose which variant to approve and deploy. Winner selection is how you mark your preferred solution.
+
+## Winners and Losers
+
+Each variant in a task group can be marked as:
+
+- **Winner**: The best variant—approved changes will come from this one
+- **Loser**: This variant had issues and should be excluded
+- **Neutral**: Neither winner nor loser (default state)
+
+Only one variant can be the winner at a time. Marking a new winner automatically clears the previous one.
+
+### Why Mark Variants?
+
+- **Clarity**: When multiple agents succeeded, marking a winner makes your choice explicit
+- **Approval flow**: The winner is what gets committed when you approve
+- **Exclusion**: Marking losers removes them from consideration
+- **Audit trail**: Track which variants were considered and why
+
+## Selecting a Winner
+
+1. Open the task group (click the group in your task list)
+2. Review each variant's changes, summary, and test results
+3. Click **Mark as Winner** icon on your preferred variant
+4. The group updates to show your selection
+
+You can change your mind at any time by marking a different variant as winner.
+
+## Reviewing Variants
+
+Before selecting a winner, review what each agent produced:
+
+### Code Changes
+
+View the diff for each variant to see exactly what changed. Look for:
+
+- Correct implementation of requirements
+- Clean, readable code
+- Appropriate error handling
+- No unintended side effects
+
+### Summary
+
+Each agent produces a summary explaining what it did. Compare summaries to understand different approaches and any issues encountered.
+
+### Test Results
+
+Check whether tests passed for each variant. A variant with failing tests may need follow-up work before it's ready to approve.
+
+### Exit Status
+
+Variants that completed successfully show exit code 0. Non-zero exit codes indicate the agent encountered an error—review the logs to understand what happened.
+
+## Marking Losers
+
+If a variant is clearly unsuitable, mark it as a loser:
+
+1. Click **Mark as Loser** icon on the variant
+2. The variant is visually de-emphasized
+3. It's excluded from comparisons and judge evaluations
+
+You can unmark a loser if you change your mind.
+
+## After Selection
+
+Once you've selected a winner:
+
+- **Review in detail**: Open the winner to examine changes closely
+- **Run the application**: Test the modified code in the container
+- **Provide feedback**: If adjustments are needed, send follow-up instructions
+- **Approve**: When satisfied, approve to commit the changes
+
+See **Approval & Deployment** for the next steps after selecting a winner.

package/dist/web-ui/public/docs/templates/batch-processing.md

@@ -0,0 +1,152 @@
+# Batch Processing
+
+Batch processing lets you run the same template against many inputs at once. Instead of manually running a template 200 times, select 200 items and let the system create and manage all the tasks automatically.
+
+## Why Batch Processing?
+
+Consider a modernization project with 500 RPG programs to convert. Without batch processing:
+
+- Run the template manually for each program
+- Wait for completion, review, approve
+- Repeat 500 times over weeks or months
+
+With batch processing:
+
+- Select all 500 programs
+- Click Run All
+- Tasks execute in parallel
+- Review and approve as they complete
+- Turn months/years of work into weeks
+
+The template ensures every program gets the same careful treatment. The batch operation handles the scale.
+
+## How It Works
+
+### Multi-Select Parameters
+
+Templates can mark parameters as supporting multiple selection. When you encounter such a parameter:
+
+1. The prompt allows selecting multiple items (files, options, etc.)
+2. A counter shows how many items you've selected
+3. The **Run All** button shows the total tasks that will be created
+
+### Task Creation
+
+When you click Run All:
+
+1. The system creates one task per selected item
+2. Each task receives the template with that item's value substituted
+3. Tasks enter the queue and execute as slots become available
+4. Parallel execution is limited by your configured queue slots
+
+### Monitoring Batch Progress
+
+After launching a batch:
+
+- View all created tasks in the Tasks list
+- Filter by template name to see just your batch
+- Monitor progress as tasks complete
+- Pin tasks that need attention
+
+## Running via CLI
+
+You can also run templates from the command line using the `coder` CLI:
+
+```bash
+# Run a template with a single value
+coder run convert-to-modern-rpg --source_file=MYPGM.rpgle
+
+# Run with multiple values (creates multiple tasks)
+coder run convert-to-modern-rpg --source_file=PGM1.rpgle --source_file=PGM2.rpgle
+
+# Specify environment and branch
+coder run convert-to-modern-rpg --environment=pjs-dev --branch=feature-xyz --source_file=MYPGM.rpgle
+```
+
+CLI execution is useful for:
+
+- **Scripted workflows**: Integrate template runs into shell scripts or automation
+- **CI/CD pipelines**: Trigger batch processing from build systems
+- **Programmatic input**: Generate the list of items to process dynamically
+
+See **CLI** in the Working with Code section for full command reference.
+
+## Cartesian Products
+
+When multiple parameters support multi-select, you get a cartesian product—every combination of selections.
+
+### Example
+
+A template with two multi-select parameters:
+
+- **Source files**: Select 10 files
+- **Target formats**: Select 3 formats
+
+Result: 30 tasks (10 files × 3 formats)
+
+Each task processes one file in one format. Every combination is covered.
+
+### Practical Limits
+
+The UI warns you when combinations exceed practical limits. Creating thousands of tasks is technically possible but may not be the best approach—consider breaking the work into smaller batches.
+
+## Batch Workflow
+
+### 1. Validate the Template First
+
+Before running at scale:
+
+1. Run the template with a single representative item
+2. Review the results carefully
+3. Verify the output meets expectations
+4. Fix any issues in the template
+
+Never batch-process hundreds of items with an untested template.
+
+### 2. Start with a Small Batch
+
+Once the template works for one item:
+
+1. Select 5-10 similar items
+2. Run the batch
+3. Review all results
+4. Confirm consistency across the batch
+
+This catches edge cases the single-item test might miss.
+
+### 3. Scale Up
+
+When confident in the template:
+
+1. Select the full set of items
+2. Run the batch
+3. Monitor progress
+4. Review and approve as tasks complete
+
+### 4. Handle Failures
+
+Some tasks may fail due to:
+
+- Edge cases the template doesn't handle
+- Unusual input that needs special treatment
+- Transient errors (retry these)
+
+Review failed tasks individually. You may need to:
+
+- Adjust the template and re-run failed items
+- Handle exceptions manually
+- Exclude certain items from batch processing
+
+## Best Practices
+
+**Test before scaling**: Always validate with single items and small batches first.
+
+**Use meaningful names**: Template names and parameters should make batch results easy to identify.
+
+**Monitor queue depth**: Large batches may take time if queue slots are limited. Plan accordingly.
+
+**Review incrementally**: Don't wait for all tasks to complete. Review and approve as they finish.
+
+**Group related work**: Batch similar items together. Mixing very different inputs may produce inconsistent results.
+
+**Plan for failures**: Expect some percentage of tasks to need individual attention. Build this into your timeline.

package/dist/web-ui/public/docs/templates/task-templates.md

@@ -0,0 +1,44 @@
+# Task Templates
+
+Task templates are reusable task definitions with parameters. Define a template once, then run it with different inputs—whether for a single item or hundreds at once.
+
+## What Are Templates?
+
+A template combines:
+
+- **Instructions**: The task description agents will follow
+- **Parameters**: Variables that customize the task for specific inputs (like which file to process)
+- **Prompts**: UI elements that let you select parameter values (file browsers, dropdown lists, etc.)
+
+Templates are configured per environment by administrators. When you run a template, you provide values for its parameters, and the system creates tasks with those values filled in.
+
+## Running a Template
+
+1. Open the **Templates** section from the home page
+2. Select your environment and template
+3. Fill in the required parameters using the provided prompts
+4. Click **Run** to create a task
+
+The template renders with your parameter values and launches as a normal task. You can monitor progress, review results, and approve changes just like any other task.
+
+## Batch Processing
+
+Templates become especially powerful when you need to process many items. Select multiple values for a parameter and run the template against all of them at once—turning weeks of manual work into overnight batch operations.
+
+See **Batch Processing** for details on multi-select parameters, cartesian products, and workflow best practices.
+
+## Common Use Cases
+
+Templates are commonly used for code modernization, refactoring, testing, and documentation tasks.
+
+See **Template Examples** for specific use cases including RPG modernization, language migration, and batch refactoring patterns.
+
+## Configuration
+
+Templates are defined in your environment's configuration. Administrators create templates with:
+
+- Markdown instructions containing parameter placeholders
+- Parameter definitions specifying prompts and validation
+- Multi-select settings for batch processing
+
+See **Environments** in the Administration section for configuration details.