WorkJinn Overview

WorkJinn daylight overview
WorkJinn brings project setup, expert-board planning, action cycles, evidence, and completion into one local workflow.

WorkJinn helps start, analyze, plan, execute, test, review, and complete a project through bounded work cycles. It is designed around concrete actions and evidence, not only planning text.

The normal local workflow route is LM Studio with the model you have loaded locally. Cloud providers such as DeepSeek can also be configured in Settings when you want to use an online model.

This help file is organized as an operating manual. Start with Getting Started, use the Mask-by-Mask Guide for visible controls, use Workflows for how the pieces fit together, and use Sample Projects when you need a concrete starting pattern.

Main Capabilities

  • Choose a task type and launch a guided Quick Start flow.
  • Create WorkJinn-managed projects or adopt existing codebases in sidecar mode.
  • Use provider routing for local AI, cloud AI, command-line providers, and transcription.
  • Run goal definition, elaboration, expert-board review, execution, validation, and completion stages.
  • Use Batch Lab for file-list, filter, transform, review, merge, retry, and improve workflows.
  • Use Autopilot to continue bounded action cycles until done, blocked, or stopped by configured limits.
  • Use book quality criteria to reject weak chapters and route them through correction before acceptance.
  • Recover safely from stale Autopilot locks after confirming that no WorkJinn run is active.
  • Keep evidence in project-local folders and logs for later review.

Typical Flow

  1. Start WorkJinn and choose the task type.
  2. Select a provider, project folder, and prompt in Quick Start.
  3. Review the dashboard fields that were filled automatically.
  4. Start the relevant workflow stage or action cycle.
  5. Inspect logs and generated project evidence before continuing.
For normal local use, select LM Studio as the AI provider and use the tool connection configured in Settings for file and command actions. WorkJinn keeps those actions separate from the AI conversation so the result can be checked from files and logs.

Current Achievements

  • All task types have predefined default expert boards.
  • Book writing keeps chapter files separate from planning notes, tool output, and continuity records.
  • Book projects can persist reject criteria for repetition, character regression, continuity conflicts, metadata leakage, future-beat spoilers, and weak endings.
  • Existing-code adoption creates a sidecar baseline inside .workjinn without modifying source files.
  • Plan, prompt-discovery, documentation, bug-fix, file-set, and test tasks create visible artifacts before work is accepted.
  • First-run defaults are set up for a local LM Studio workflow.

Detailed Reference Pages

Page | Contents
Sample Projects | Ready-to-follow examples for existing code, live certification, documentation, batch cleanup, bug repair, and new-code planning.
Choose Your Task | Startup task choices, Start Task, Dashboard, close behavior, and remembered position.
Quick Start Wizard | Provider, project folder, prompt, adoption checkbox, Back, Next, Start, Cancel, and Transcribe.
Dashboard | Main dashboard fields, route selectors, project commands, and workflow buttons.
Settings | General settings, provider settings, stage routing, probes, timeouts, and model refresh.
Task Wizards | Book, existing code, plan, idea, prompt, file set, bug, test, and documentation wizards.
Goal and Elaboration | Goal refinement, approval, elaboration, and artifact buttons.
Experts | Expert board, board presets, expert editor fields, and related buttons.
Action Cycle | Discussion, work order, execution, validation, review, and advance controls.
Batch Lab | Source list, filters, LLM routing, retry, review, merge, and extension settings.
Logs, Save/Load, Editors | Logs, snapshots, project loading, text prompts, text editor, progress dialog, and prompt settings.
Copyright, Legal, and AI Use | Separate legal notices, AI-output cautions, secrets, provider terms, and warranty disclaimer.


What Is New

WorkJinn update visual
Recent WorkJinn updates focus on safer starts, clearer recovery, stronger book workflows, and easier local AI operation.

Better Quick Start

  • Task choices now lead into focused wizard pages instead of one generic setup flow.
  • Provider, folder, and prompt choices are carried into the dashboard automatically.
  • Tool testing separates AI chat readiness from local file and command readiness.

Book Workflow Improvements

  • Book projects can continue from existing chapters instead of restarting the story.
  • Continuity notes are kept outside reader-facing chapter files.
  • Quality criteria can force correction passes for repetition, continuity problems, metadata leakage, spoilers, weak endings, and character regression.

Safer Project Work

  • Existing projects use a sidecar folder so WorkJinn state does not take over the source folder.
  • Action cycles keep discussion, work order, execution, validation, and review artifacts separate.
  • Autopilot has clearer stop reasons for done, blocked, timeout, retry limit, and lock cases.
  • The dashboard now asks before clearing an Autopilot lock, then continues automatically when the user confirms the stale lock should be removed.

Clearer Local AI Operation

  • Settings now make it easier to test providers before long runs.
  • Timeouts help avoid waiting forever when a model is busy or unavailable.
  • Logs and review pages show the provider, result state, and evidence path more clearly.

Simpler Distribution

The public WorkJinn package is intentionally small: the application, this help file, a readme, hashes, and the version file. Workspaces, logs, settings, and generated project files are created locally when the user runs WorkJinn.


Quick Start Wizard

Quick Start Wizard visual
Quick Start collects the minimum provider, folder, and prompt details needed to begin work.

The Quick Start Wizard collects only the fields needed for the selected task and then prepares the dashboard automatically.

Steps

Step | Purpose
Provider | Choose the AI route used for analysis or first workflow setup. LM Studio is the normal local live route.
Project Folder | Select an existing project folder, reopen an adopted WorkJinn sidecar, or create a new folder when the task supports it.
Prompt | Describe the goal, bug, documentation task, test area, or implementation plan. This text seeds project goal artifacts.
Quality Criteria | For book tasks, choose which chapter defects force a correction pass. All criteria are enabled by default.

Book Quality Criteria

When the selected task is writing or recovering a book, Quick Start shows a quality-criteria page before launch. The checked criteria are saved under .workjinn\80_Book\QualityCriteria.cfg and are used by the board to reject a chapter before it becomes accepted output.

  • Repetition: rejects chapters that loop the same scene, paragraph pattern, or conflict without progress.
  • Character regression: rejects chapters that undo established character choices without story reason.
  • Continuity conflicts: rejects contradictions against earlier chapters or continuity notes.
  • Metadata leakage: rejects tool-plan text, YAML/frontmatter, command logs, or internal instructions in manuscript files.
  • Future-beat spoilers: rejects notes that reveal future chapter planning inside reader-facing text.
  • Weak endings: rejects chapters that stop abruptly, summarize the missing scene, or end without a usable handoff.

Start Task Behavior

After pressing Start, WorkJinn either reopens an existing WorkJinn project or runs adoption analysis for a new external project. When the setup succeeds, the dashboard receives the provider, project folder, and prompt-derived goal automatically.

Window Position

The task selector and task-entry dialogs remember the last startup wizard position. If the saved position is outside the current screen layout, WorkJinn opens the form centered instead.

During project adoption, the progress dialog should be allowed to finish. Recent builds ignore manual close while the worker is active to avoid interrupting the handoff from analysis back to the dashboard.


Dashboard

Dashboard guide visual
The dashboard is the main control surface for projects, routes, goals, stages, and evidence.

The dashboard is the main control surface. It shows the active workspace, current goal, resolved provider routes, and stage status.

Main Areas

  • Workspace controls: create, load, or adopt projects.
  • Settings: configure providers, routes, timeouts, and related options.
  • Goal: define, refine, approve, and reopen goal artifacts.
  • Elaboration: prepare execution dossiers and subgoals.
  • Experts: maintain expert libraries and the active board.
  • Cycle: run discussion, execution, validation, and review.
  • Batch: process groups of files through list/filter/transform/review operations.
  • Logs: open application, project, provider, and evidence logs.

Dashboard After Quick Start

When Quick Start succeeds, the dashboard should open with the selected project loaded, the chosen provider persisted for definition, and the prompt written into the raw goal path.


Sample Projects

Sample project planning visual
Sample projects show which mask to open, what to enter, what WorkJinn creates, and which evidence to inspect.
Use these examples as starting patterns. They are intentionally small enough to understand, but they exercise the same WorkJinn masks and artifacts used by real projects.

How to use a sample

  1. Open WorkJinn and choose the matching task type in Choose Your Task.
  2. Enter the sample values into the wizard or dashboard.
  3. Run the suggested stage or cycle.
  4. Open Logs and the cycle folder to inspect evidence.
  5. Only continue when the validation and review artifacts match the expected outcome.

Sample 1: Small Utility Project

Item | Value
Best task | Work on existing code
Example folder | tests\fixtures\MiniPBUtility
Goal prompt | Verify the small utility project, explain its run output, and produce a compact handoff report.
Recommended route | Local/deterministic first. Use LM Studio only for explanation or review text.
Useful masks | Quick Start, Goal, Elaboration, Action Cycle, Logs.
Expected evidence | Run output, result text, and cycle validation notes.

This is the simplest coding sample. Use it to learn adoption, goal approval, and cycle validation without a large codebase.

Sample 2: Live Certification Fixture

Item | Value
Best task | Work on existing code
Example folder | tests\fixtures\LiveCertFixture
Goal prompt | Run the certification-style fixture through validation, review, and completion.
Recommended route | LM Studio for planning and review; deterministic project checks for proof.
Useful masks | Settings, Experts, Action Cycle, Logs, Autopilot and Completion.
Expected evidence | Run transcript, result file, review verdict, and completion report.

This sample is useful when testing the full WorkJinn evidence chain. It demonstrates why logs and validation artifacts matter more than a model's final prose.

Sample 3: Documentation Refresh

Item | Value
Best task | Write docs
Example folder | Your project folder, or a small fixture folder
Goal prompt | Update the user-facing documentation so a new operator can install, configure, run, troubleshoot, and verify the project.
Recommended route | LM Studio for drafting; human review before approval.
Useful masks | Task Wizards, Goal, Elaboration, Experts, Logs.
Expected evidence | Changed documentation files, review notes, and an explicit list of what was not changed.

Use this sample when the goal is clarity, not code changes. Keep acceptance criteria focused on reader tasks and missing information.

Sample 4: Batch Cleanup

Item | Value
Best task | Process a file set
Example source | A folder with duplicated text, stale docs, or generated reports.
Goal prompt | Find candidate files for cleanup, classify them, propose safe changes, and merge only reviewed output.
Recommended route | Deterministic filters first; LLM review only after file selection is narrow.
Useful masks | Batch Lab, Experts, Logs.
Expected evidence | Batch list, filter decisions, review decisions, retry log if any, and merge output.

This sample teaches safe batch discipline: preview before create, use exclude masks, and separate deterministic filtering from provider-assisted review.

Sample 5: Bug Repair

Item | Value
Best task | Fix a bug
Example folder | Any small project with a reproducible failure.
Goal prompt | Fix the reported failure, preserve existing behavior, and prove the fix with the smallest meaningful test evidence.
Recommended route | LM Studio for analysis and review; enable the local tool connection only when file or command operations are required.
Useful masks | Bug wizard, Goal, Action Cycle, Logs.
Expected evidence | Failure description, changed files, test output, and review verdict.

Write the observable symptom in the wizard. Do not start with only a suspected root cause.

Sample 6: New Code From Plan

Item | Value
Best task | Create a new code project
Example input | A short markdown plan with scope, constraints, and acceptance criteria.
Goal prompt | Implement the approved plan in a new project folder, keeping generated files minimal and verifiable.
Recommended route | Plan Then Code for rough ideas; New Code From Plan for already approved specs.
Useful masks | Task Wizards, Settings, Action Cycle, Logs.
Expected evidence | Created project files, run instructions, validation result, and handoff notes.

Sample acceptance checklist

  • The active project folder is correct before the cycle starts.
  • The approved goal is specific enough to validate.
  • The provider route is intentional, not accidental fallback.
  • The cycle produces discussion, work order, execution, validation, and review artifacts.
  • The final review verdict is supported by visible output, not only a model answer.


Mask: Choose Your Task

Startup mask. Use this when you want WorkJinn to prepare the correct workflow before the dashboard opens.
Choose Your Task visual
Visual guide image for the startup choice mask. Exact controls are described below.

What this mask does

The Choose Your Task mask prevents an empty dashboard start. It asks what kind of work you are about to do, then opens the matching wizard or the dashboard. The selected task becomes the seed for project creation, folder adoption, goal text, and later action-cycle setup.

Controls and buttons

Control | What it means | What happens when you use it
Task list | List of supported work types such as existing code, new code from plan, prompt discovery, file set, bug fix, add tests, write docs, and book/writing tasks. | The selected entry controls which wizard opens after Start Task.
Description panel | Plain-language preview of the selected task, including the kind of input WorkJinn expects. | Updates immediately when the selected task changes.
Start Task | Main action button for the selected task. | Closes only the selector mask and opens the matching wizard. It must not terminate WorkJinn.
Dashboard | Bypass task-specific setup. | Opens the main dashboard directly. Use this when a project is already configured or you want manual control.
Close / X | Exit the startup selector. | Returns to the caller. The last usable window position is saved for the next run.

Task choices

Task | Follow-up mask | Typical input
Work on existing code | Quick Start or Existing Code wizard | Folder, project name, language, test hints, initial request.
Create a new code project | New Code From Plan, Plan Then Code, or Prompt Discovery wizard | Plan file or prompt, language, output folder, project name.
Fix a bug | Bug Fix wizard | Bug description, target folder, project name.
Add tests | Add Tests wizard | Test focus, target folder, project name.
Write docs | Write Docs wizard | Documentation focus, folder, project name.
Process a file set | File Set wizard or Batch Lab | Source folder and batch/file-selection intent.
Book or writing task | Book wizard | Title, author, genre, chapter count, target words.

Operator notes

  • Use Dashboard when you need direct access to settings, logs, or an already loaded project.
  • Use Start Task when you want WorkJinn to prefill the dashboard and goal artifacts from a guided wizard.
  • If the mask opens off screen after monitor changes, WorkJinn recenters it when the saved position is invalid.

User tip

Choose the task that matches the outcome, not the technology. For example, documentation cleanup should start as Write Documentation even when the project is a code project.


Mask: Quick Start Wizard

Guided startup mask. Use it to choose provider, folder, and prompt before the dashboard runs work.
Quick Start Wizard visual
Quick Start visual guide. Exact page and button behavior is listed below.

What this mask does

The Quick Start Wizard collects the minimum information required for a runnable WorkJinn session. It applies provider selection, project folder choice, and the initial prompt so the dashboard can start with meaningful state instead of blank fields.

Wizard pages

Page | Fields | Purpose
Provider | Provider list, model/status description, refresh/test actions. | Selects the first workflow route. LM Studio is the controlled local green lane for live workflow work.
Project Folder | Folder path, Browse, New Folder, adoption option. | Chooses whether WorkJinn creates a managed project or adopts an existing external folder.
Prompt | Prompt editor, hint text, optional transcription entry. | Captures the user request that seeds goal definition and dashboard fields.
Quality Criteria | Book quality reject checkboxes. | Controls which chapter defects make the board reject output and request correction.
Progress | Status text, phase messages, progress state. | Shows folder adoption, setup, or provider/tool checks while a worker is active.

Buttons

Button | Meaning | Result
Back | Return one wizard page. | Keeps already entered provider, folder, and prompt values.
Next | Advance one wizard page. | Validates required fields on the current page before continuing.
Finish / Start | Complete setup. | Applies provider, folder, and prompt to the dashboard. Adoption may run if requested.
Cancel | Stop setup. | Closes the wizard without launching the task.
Browse | Select an existing folder. | Fills the project-folder field.
New Folder | Create or select a new workspace folder. | Prepares a clean project location.
Refresh | Refresh provider/model information. | Updates visible endpoint/model state where the provider supports it.
Save Model | Persist selected model hint. | Stores model choice in local settings for later runs.
Test Tools | Check AI chat and local tool readiness. | Reports AI connectivity and tool-lane availability separately.
Transcribe | Use the configured transcription route. | Inserts or updates prompt text from audio when configured.

Book quality page

For Write a Book and Recover Book Project, Quick Start adds a quality page before the final start. All rejection criteria start checked. Uncheck only criteria that should be advisory instead of blocking for the current book.

Checkbox | Rejects
Repetition | Repeated scene beats, circular dialogue, or no real chapter movement.
Character regression | Character choices or relationships that contradict previous accepted chapters.
Continuity conflicts | Timeline, setting, object, or lore conflicts against manuscript context.
Metadata leakage | Tool plans, YAML/frontmatter, command output, reviewer notes, or internal instructions in chapter text.
Future-beat spoilers | Outline notes for later chapters placed in reader-facing manuscript text.
Weak endings | Aborted chapters, summary endings, or endings that do not hand off to the next chapter.

Important behavior

  • Adoption mode creates sidecar state under .workjinn in the selected external project.
  • Book quality criteria are stored in .workjinn\80_Book\QualityCriteria.cfg and travel with the project sidecar.
  • Test Tools does not mean the AI itself can write files. File and command operations use the configured local tool lane.
  • Real provider secrets must stay local. Do not place real API keys into package files.

User tip

If Quick Start stops, reopen the same project folder from the dashboard. WorkJinn stores project state so a stopped setup or run can usually be continued instead of restarted from nothing.


Mask: Dashboard

Main control mask. Every major WorkJinn workflow can be opened or started here.
Dashboard visual guide. The table below explains every main control group.

What this mask does

The Dashboard is the central WorkJinn operating surface. It shows the active workspace, active project, goal summary, provider route, board state, cycle state, and entry points for all work stages.

Project controls

Control | Meaning | Result
Workspace / Root display | Current WorkJinn workspace root. | Used as the default parent for managed projects.
Current Project | Name and folder of the active project. | All workflow buttons operate on this project.
New Project | Create a managed WorkJinn project. | Prompts for a name, creates folders, and activates the new project.
Load Project | Open the project-load mask. | Activates an existing WorkJinn project.
Adopt Project / Adopt External | Attach WorkJinn to an existing folder. | Creates or uses sidecar state under .workjinn and analyzes the target.
Save / Load | Open snapshot save/load. | Saves or restores selected state areas.

Stage buttons

Button | What it opens | Primary output
Goal | Goal Definition mask. | Raw, refined, and approved goal artifacts.
Elaboration | Goal Elaboration mask. | Expanded requirements, constraints, and subgoal guidance.
Experts | Expert Board mask. | Active board members, order, presets, and behavior definitions.
Cycle | Action Cycle mask. | Discussion, work order, execution, validation, review, next-state decision.
Batch | Batch Lab mask. | File lists, filter decisions, transforms, reviews, retries, merges.
Prompts | Prompt Settings mask. | Editable prompt templates, model hints, local-model behavior text.
Settings | Settings mask. | Provider, route, timeout, project root, and model settings.
Logs | Logs mask. | Application, provider, project, cycle, execution, and evidence logs.
START / Start Work | Runs the configured dashboard workflow. | Starts the selected project/action path with current routes and board settings.

Status and routing panels

Area | Use
Goal summary | Confirms what WorkJinn believes it is trying to complete.
Board summary | Shows the current expert board or selected board preset.
Resolved routes | Shows which provider is selected for definition, elaboration, discussion, execution, testing, review, completion, and transcription.
Cycle status | Shows the active cycle, last verdict, and next recommended action.

Operator notes

  • Always check the Current Project line before pressing START.
  • Use Settings before the first live run to confirm the provider, model, and tool connection.
  • Use Logs after a run. WorkJinn is evidence-driven; failures are normally explained in the latest log or cycle folder.

User tip

Before pressing Start Work, confirm the project folder, approved goal, selected task type, and route labels. That prevents accidental work in the wrong folder.


Mask: Settings

Configuration mask for project roots, providers, stage routes, timeouts, parallelism, and local-model safeguards.
Settings visual guide. Provider, route, and safety controls are explained below.

General controls

Control | Meaning | Result
Projects root | Default parent folder for WorkJinn-managed projects. | New projects and project lists use this path.
Save | Write settings to local configuration. | Updates the settings used by future runs.
Close | Leave settings. | Keeps current in-memory values; saved values persist after restart.
Status | Message area for validation and test results. | Shows save result, provider test output, model refresh result, or error text.

Provider controls

Control | Meaning | Result
Provider selector | Choose a local AI, cloud AI, command-line provider, tool provider, or transcription provider. | Loads that provider's settings into the visible fields.
Enabled | Marks provider available. | Provider can be used by routing when eligible.
Workflow Eligible | Marks provider usable in WorkJinn workflow stages. | Route resolution may select it for stages.
Path / Base URL | Executable path or OpenAI-compatible endpoint. | Used for CLI providers or HTTP providers such as LM Studio.
Working Dir | Provider working folder. | Used for CLI provider launches and output resolution.
Output Dir | Provider run output folder. | Stores provider evidence and run artifacts.
API key | Local secret value where required. | Used only at runtime. Do not ship real secrets.
Model | Model id or local loaded model name. | Used in chat/completion requests.
Auto-Configure | Fill common local defaults. | Useful for LM Studio and common local paths.
Test | Run a basic provider check. | Verifies endpoint or executable reachability.
Capability Probe | Check workflow/tool capability. | Records whether file read/write, command execution, test execution, or transcription are available.
Refresh Models | Request model list from compatible endpoints. | Updates cached model names when supported.
Save Provider | Persist the selected provider panel. | Writes provider-specific fields to config.

Routing and safeguards

Control | Description
Definition, Elaboration, Expert Board, Discussion, Execution, Testing, Review, Completion, Transcribe routes | Choose which provider handles each stage.
Timeout fields | Bound provider, execution, and autopilot waits so long runs do not hang forever.
Parallel workers | Caps safe worker concurrency for provider queues.
Tool connection mode and URL | Controls the local lane used for file and command actions.
Answer Guard | Optional self-check and retry layer for weaker local model outputs.
Better Prompt / Prompt Refiner | Optional prompt preprocessing before the real provider call.

Operator notes

  • For controlled local work, use LM Studio for chat and the configured local tool connection for file and command operations.
  • Store real secrets only in local environment/settings, not in release package files.

User tip

Use Test before a long run. A provider can be installed but still unavailable if no model is loaded, a key is missing, or the endpoint is not running.


Mask: Task Wizards

Task-specific setup masks. They create the first project state before dashboard work begins.
Task wizard visual
Task wizard visual guide. Each wizard has the same purpose: collect enough structured input for WorkJinn to start correctly.

Common buttons

Button | Meaning | Result
Browse | Select a file or folder. | Fills the matching path field.
Create | Create the project scaffold from entered values. | Writes initial project state and goal material.
Load | Use an existing plan, folder, or project input. | Copies or references the selected source into project state.
Start | Create/load and continue into the workflow. | Opens the dashboard or starts the configured follow-up flow.
Cancel | Leave the wizard. | No new task is applied.

Wizard inventory

Wizard | Fields | What it prepares
Book | Title, author, genre, chapters, target word count, folder. | Writing project scaffold and chapter-oriented goal text.
Existing Code | Project folder, project name, language, test or run hint. | Sidecar adoption and code-analysis prompt.
New Code From Plan | Plan file, language, project name, output folder. | Implementation project from an approved plan/specification.
Plan Then Code | Idea description, language, project name, output folder. | Planning-first project where WorkJinn creates a plan before implementation.
Prompt Discovery | Prompt text, project name, output folder. | Broad prompt converted into a structured WorkJinn goal.
File Set | Project name, source folder, browse path. | Focused file-set or batch-oriented project state.
Bug Fix | Bug description, folder, project name. | Defect-repair task with an explicit failure description.
Add Tests | Test focus, folder, project name. | Test-expansion task with verification emphasis.
Write Docs | Documentation focus, folder, project name. | Documentation task tied to the selected project or source folder.

Field guidance

  • Use clear project names. They become folder and artifact labels.
  • For existing code, pick the real project root, not an inner output folder.
  • For plan-based work, choose the highest-level plan file that contains scope, constraints, and acceptance criteria.
  • For bug-fix and test tasks, write the observable symptom or missing test behavior, not only the suspected implementation cause.

User tip

Good wizard input names the wanted result, the important files or folders, and the evidence that should prove the result. Short, concrete prompts work better than long background essays.


Mask: Goal and Elaboration

Planning masks. They turn the user's rough request into approved goal and execution guidance.
Goal and elaboration visual
Goal and elaboration visual guide. These masks create the approved intent WorkJinn executes against.

Goal Definition mask

Button or field | Meaning | Result
Raw goal editor | User-entered request or wizard-seeded task text. | Stored as the initial goal input.
Run AI | Ask the configured definition provider to refine the raw goal. | Writes a refined goal artifact with scope and intent.
Open Refined | Open the generated refined goal file. | Lets the user inspect or edit before approval.
Approve | Promote the current refined goal. | Creates the approved goal artifact used by elaboration and cycles.
Open Approved | Open approved goal file. | Confirms the exact goal WorkJinn will execute.
Close | Leave the mask. | Returns to dashboard.

Goal Elaboration mask

Button or field | Meaning | Result
Working editor | Editable elaboration draft. | Contains requirements, constraints, success notes, and work guidance.
Run AI | Ask the configured elaboration provider to expand or improve the draft. | Writes a fuller elaboration artifact.
Approve | Promote the elaboration. | Marks the elaboration ready for expert discussion and cycles.
Open Approved | Open the approved elaboration artifact. | Shows the current execution dossier.
Close | Leave the mask. | Returns to dashboard.

Operator notes

  • Do not approve a vague goal. The action cycle depends on approved wording.
  • Use elaboration to capture non-negotiable constraints such as file formats, provider lanes, release rules, and test gates.
  • When a provider answer is weak, use Answer Guard or rerun with a clearer prompt before approval.

User tip

Do not approve an elaboration that cannot be checked. Add expected files, visible behavior, or review criteria before moving into the action cycle.


Mask: Experts and Expert Editor

Board masks. They define which expert perspectives review, discuss, and steer a WorkJinn project.
Expert board visual
Expert board visual guide. Use these masks to control board membership and expert behavior.

Experts board mask

Control | Meaning | Result
Library list | All available expert definitions. | Select experts to add or edit.
Active list | Experts assigned to the current board. | These experts participate in board prompts and review decisions.
Add | Move selected library expert to active board. | Expert becomes part of the current board.
Remove | Remove selected active expert. | Expert stays in library but no longer participates in this board.
New | Create a new expert definition. | Opens the Expert Editor mask.
Edit | Edit selected expert. | Opens the Expert Editor with existing fields.
Delete | Delete selected expert definition. | Removes it from the library after confirmation.
Up / Down | Change active board order. | Controls discussion/review ordering.
Board name | Name for the active board. | Stored with current board metadata.
Enabled | Controls whether the board is used. | Disabled boards are ignored by board routing.
Preset Save / Load / Delete | Manage reusable board presets. | Stores or restores board membership and order.
Save | Persist active board state. | Writes board metadata and active membership.
Close | Leave the mask. | Returns to dashboard.

Expert editor mask

Field or button | Meaning | Result
Expert ID | Stable expert identifier. | Used in presets, active boards, and artifacts.
Name, domain, role, short label | Display and routing metadata. | Helps users understand the expert's job.
Seed text | Raw material for expert generation. | Used by Draft/Sharpen when building the expert definition.
Transcribe | Capture seed material from audio. | Fills or updates seed text when transcription is configured.
Draft | AI-assisted first-pass expert creation. | Fills behavior fields from seed text.
Sharpen | Improve existing expert definition. | Clarifies purpose, strengths, blind spots, evaluation, and output style.
Purpose, strengths, blind spots, evaluation, output, definition | Behavioral fields used in prompts. | Defines how the expert contributes to discussion and review.
Clear Seed | Clear only the seed text. | Does not erase the saved expert fields.
Save / Cancel | Commit or discard changes. | Updates library or returns without writing.

Operator notes

  • Use a small board for routine work and a broader board for release decisions.
  • Put critical reviewers earlier in the order when you need their constraints to influence the discussion.
  • Use presets for repeatable project types, such as software cleanup, documentation passes, book writing, or review-heavy work.

User tip

Use fewer, sharper experts for small tasks. A focused board usually produces better instructions than a large board with overlapping roles.


Mask: Action Cycle

Execution mask. This is WorkJinn's discussion, work-order, execution, validation, and review loop.
Action Cycle visual
Action Cycle visual guide. The cycle mask is where approved goals become evidence-producing work.

What this mask does

The Action Cycle mask runs the core WorkJinn loop. A board discusses the next step, creates a work order, executes through the selected route, validates results, and reviews whether to retry, improve, mark a subgoal done, mark the whole goal done, or report blocked state.

Buttons and fields

Button or field | Meaning | Result
Edit | Open current request or state text. | Lets the operator adjust cycle input before running.
Review | Open review material for the current cycle. | Shows the current board review or decision file.
Open Folder | Open active cycle folder. | Displays all artifacts for the current cycle.
Start | Run the action cycle orchestrator. | Creates or updates discussion, work order, execution, validation, and review artifacts.
Open Discussion | Open expert-board discussion output. | Shows reasoning and proposed next work order.
Open Work Order | Open the generated work order. | Shows exact instructions passed to execution.
Open Execution | Open execution artifacts. | Shows provider/tool output and changed-file evidence.
Open Validation | Open validation artifacts. | Shows checks, test results, and acceptance evidence.
Open Review | Open board review output. | Shows final cycle verdict and feedback.
Advance | Move to the next cycle state when permitted. | Prepares the next cycle after a valid decision.
Close | Leave the mask. | Returns to dashboard.

Cycle verdicts

Verdict | Meaning
RETRY | The work failed; run another attempt with the same objective.
IMPROVE_RESULT | The work is usable but needs focused refinement.
SUBGOAL_DONE | The current subgoal is complete; move to the next subgoal.
GOAL_DONE | The full project goal is complete and ready for handoff/completion.
BLOCKED | Work cannot continue without user input or an external state change.

Operator notes

  • Open Validation before trusting a successful-looking execution result.
  • Use Open Folder when diagnosing because all evidence for the cycle is grouped there.
  • For file and command actions, confirm that the tool connection is configured before running live execution.

User tip

If a cycle does not accept the result, open Discussion, Work Order, Execution, Validation, and Review in that order. The reason is usually visible in the first stage that does not match the requested outcome.


Mask: Batch Lab

Bulk-work mask. Use it to list, filter, transform, review, retry, and merge many files.
Batch Lab visual
Batch Lab visual guide. The real mask separates source selection, filtering, action routing, and merge/review operations.

Source list controls

Control | Meaning | Result
Source path | Folder to scan. | Batch file discovery starts here.
Pick / Browse | Select source folder. | Fills source path.
Recursive | Include subfolders. | Broadens the file scan.
Hidden / System | Include hidden/system files. | Use carefully; normally leave off for code/document batches.
Include extensions | Allowed file extensions. | Limits batch to specific file types.
Exclude extensions | Blocked file extensions. | Prevents binaries, logs, or generated output from entering the batch.
Include masks | Wildcard names to include. | Focuses the batch on matching files.
Exclude masks | Wildcard names or folders to ignore. | Useful for output folders, vendor folders, and generated assets.
Minimum / Maximum size | File-size limits. | Avoids tiny irrelevant files or very large files.
Preview | Preview included files. | Shows what will be in the batch before state is written.
Create | Create batch state. | Writes the batch list and metadata.

List, filter, and run controls

Control | Meaning | Result
Load | Load current or selected batch. | Displays stored batch items.
Rescan | Rebuild list from source folder. | Updates entries after files changed.
Save | Persist current batch state. | Writes decisions and metadata.
Open Folder | Open batch state/output folder. | Shows generated artifacts.
Path contains / not contains | Deterministic path filters. | Marks matching entries for keep/drop/review decisions.
Filename / extension / size / status | Additional deterministic filters. | Targets specific subsets.
Simple / LLM | Choose deterministic or provider-assisted filtering. | Controls whether WorkJinn asks a model to judge items.
Keep / Drop / Review | Manual decision buttons. | Sets selected item status.
Provider | Provider route for batch actions. | Chooses who performs filter/transform/review work.
Board | Board or preset for batch decisions. | Controls expert perspective for provider-assisted steps.
Action | Batch action mode such as improve or retry. | Determines how failed or reviewed items are handled.
Prepare | Prepare pending work. | Creates action-ready item state.
Pending | Run pending items. | Executes the batch pipeline for queued items.
Retry Failed | Retry failed items. | Creates a focused retry pass.
Review | Run final review. | Produces review decisions before merge.
Merge | Merge approved output. | Applies reviewed results to final output where configured.

Operator notes

  • Preview before Create. Most batch mistakes come from over-broad file selection.
  • Use exclude masks for output folders, package folders, third-party dependencies, and generated logs.
  • Keep deterministic filters separate from LLM filters when you need reproducible evidence.

User tip

Preview the list before creating a batch. Narrow batches are easier to review and safer to merge.


Mask: Logs, Save/Load, Editors

Utility masks for evidence review, project snapshots, text editing, prompt templates, progress, and project loading.
Logs and utility visual
Utility visual guide. These masks help inspect and preserve WorkJinn evidence.

Logs mask

Button | Opens | Use when
App Log | Main application log. | Startup, routing, UI, and high-level workflow behavior need diagnosis.
App Log | Main WorkJinn activity log. | You need to understand startup, provider, project, or cycle behavior.
Project Log | Current project operational log. | You need project-specific state transitions.
Run Log | Provider or run-specific log. | Provider execution or live route behavior needs inspection.
Cycles | Cycle artifact folder or log. | You need discussion, work order, execution, validation, and review artifacts.
Execution | Execution artifact folder or log. | You need changed-file, command, or provider evidence.
Evidence | Evidence folder or log. | You need proof and final state records.
Close | Closes logs. | Return to dashboard.

Save/Load Snapshot mask

Control | Meaning | Result
Save / Load mode | Choose snapshot direction. | Controls whether WorkJinn writes or restores selected stage folders.
Path field | Snapshot folder. | Destination for save or source for load.
Browse | Select snapshot folder. | Fills path field.
State, goals, definition, experts, cycles, evidence, execution, batches, logs checkboxes | Select project areas. | Only checked areas are saved or restored.
OK | Perform operation. | Writes or restores selected snapshot areas.
Cancel | Exit without changing snapshot state. | Returns to dashboard.

Other utility masks

Mask | Controls | Purpose
Project Load | Project list, filter/prompt, path field, Load, Cancel, Open Root. | Activate a managed WorkJinn project.
Text Prompt | Input field, OK, Cancel. | Collect short names, values, and command inputs.
Structured Text Editor | Save, Save and Close, Close, Notepad, Record, Transcribe, Insert, Last Transcript. | Edit stage files and prompt/evidence text.
Progress Dialog | Status text and phase counters. | Shows long-running worker state without hiding progress.
Prompt Settings | Language selector, prompt selector, editor, Save, Reset, Close, status. | Edit prompt templates and local model behavior.

Operator notes

  • When debugging, start with App Log and the current cycle folder.
  • Use snapshots before risky provider/tool runs on important projects.
  • Do not close a progress dialog expecting it to stop a worker unless that workflow explicitly supports cancellation.

User tip

When a result looks wrong, start with the latest cycle review and then inspect the matching execution and validation files. The app log is useful for startup and provider problems.


Button and Form Reference

WorkJinn controls visual
The button reference maps visible controls to their operating effect.

This page is a quick lookup for WorkJinn buttons. For more context, open the matching mask page in the Mask-by-Mask Guide.

Startup and Quick Start

Button | Mask | Effect
Start Task | Choose Your Task | Opens the wizard for the selected task type.
Dashboard | Choose Your Task | Skips startup task setup and opens the dashboard.
Back | Quick Start | Returns to the previous wizard page.
Next | Quick Start | Validates the current page and moves forward.
Finish / Start | Quick Start | Applies provider, folder, and prompt to dashboard state.
Refresh | Quick Start / Settings | Refreshes model/provider information where supported.
Save Model | Quick Start | Stores selected model hint.
Test Tools | Quick Start | Checks AI chat and local tool readiness separately.
Browse / New Folder | Quick Start and task wizards | Selects or prepares a project folder.
Transcribe | Quick Start / Editor / Expert Editor | Uses configured transcription provider to insert text from audio.

Dashboard

Button | Effect
New Project | Creates and activates a managed WorkJinn project.
Load Project | Activates an existing WorkJinn project.
Adopt Project | Creates sidecar state for an existing codebase.
Save/Load | Opens project snapshot controls.
Goal | Opens goal definition.
Elaboration | Opens elaboration and dossier setup.
Experts | Opens expert board management.
Cycle | Opens action cycle control.
Batch | Opens Batch Lab.
Prompts | Opens prompt template settings.
Settings | Opens provider, route, timeout, and safety settings.
Logs | Opens log and evidence shortcuts.
START / Start Work | Runs the configured dashboard workflow.

Settings and providers

Button | Effect
Save | Writes current settings to local configuration.
Auto-Configure | Fills common local provider defaults.
Test | Runs provider connectivity check.
Capability Probe | Checks provider/tool capability and records status.
Refresh Models | Updates model list from compatible endpoint.
Save Provider | Stores the selected provider panel.

Goal, elaboration, cycle, and batch

Button | Effect
Run AI | Uses the configured provider to refine a goal or elaboration.
Approve | Promotes the current goal/elaboration to approved state.
Open Refined / Open Approved | Opens the corresponding artifact.
Start | Runs an action cycle.
Open Discussion / Work Order / Execution / Validation / Review | Opens the current cycle artifact for that stage.
Advance | Moves the cycle forward after a valid decision.
Preview | Shows batch file selection before writing state.
Create | Creates batch state or wizard project state.
Prepare / Pending / Retry Failed / Review / Merge | Runs the selected Batch Lab pipeline step.

Good habits

Use Test Tools before a long run, open Logs after a stopped run, and use Completion only after the review decision and visible output agree with the goal.


Workflow Stages

Workflow stages visual
Workflow stages move a project from goal definition through execution, validation, review, and completion.

WorkJinn moves work through explicit stages. Each stage should leave evidence so the next stage has context.

Core Stages

Stage | Purpose
Definition | Clarify the goal and project context.
Elaboration | Prepare the executable dossier and subgoals.
Expert Board | Select expert perspectives and board routing.
Discussion | Let the board shape the next action.
Execution | Perform the work item.
Testing | Validate the result with deterministic or provider-assisted evidence.
Review | Decide retry, improve, done, goal done, or blocked.
Completion | Create a deterministic handoff package.

Review Decisions

  • RETRY: repeat the same subgoal with feedback.
  • IMPROVE_RESULT: focused retry when the result is close but incomplete.
  • SUBGOAL_DONE: advance to the next subgoal.
  • GOAL_DONE: complete the overall goal.
  • BLOCKED: stop or route around a blocker.

What Changed In The Current Workflow

The current workflow is stricter about evidence than earlier manual versions. A provider response is not enough by itself. WorkJinn now checks concrete files and evidence paths before accepting common first-cycle task results.

  • Book cycles check clean manuscript text and continuity sidecars.
  • Existing-code cycles keep adoption evidence inside .workjinn.
  • Planning and prompt-discovery cycles create reviewable plan or analysis artifacts before implementation.
  • Documentation, test, file-set, and bug-fix cycles create task-specific evidence bundles.


Projects and Sidecars

Projects and sidecars visual
Project sidecars keep WorkJinn state beside adopted projects without taking over the target source tree.

WorkJinn supports native WorkJinn projects and adopted external projects. Adopted projects use a sidecar folder so the target source tree is not turned into a WorkJinn repository.

Sidecar Folder

<target>\.workjinn\

Important sidecar folders include:

  • 10_Goals: raw, refined, approved, and working goal files.
  • 20_Definition: project analysis and definition evidence.
  • 30_Experts: project board data.
  • 40_Cycles: action cycle state.
  • 50_Evidence: validation and supporting artifacts.
  • 60_Execution: execution output and work products.
  • 70_Batches: batch workflow data.
  • 85_Completion: completion packages and handoff reports.
  • 90_Logs: project-local logs.

Adoption

Adoption scans the folder, runs analysis when configured, writes sidecar setup files, and records project state. Existing adopted projects are reopened instead of analyzed again.


Batch Lab

Batch Lab workflow visual
Batch Lab is for controlled multi-file work with reviewable inputs, outputs, retries, and merge decisions.

Batch Lab is for controlled work over a set of files. It is useful for cleanup, documentation passes, repetitive transformations, or review workflows.

Typical Batch Flow

  1. Select a source folder and list rules.
  2. Filter the file list manually or with a provider-assisted step.
  3. Run transformations or reviews on the active items.
  4. Review output and retry failed items where useful.
  5. Merge accepted output back into the project when appropriate.

Evidence

Batch outputs are written under project batch folders so each file decision and result can be inspected later.


Autopilot and Completion

Autopilot and completion visual
Autopilot and completion keep long-running work bounded, reviewed, and ready for handoff.

Autopilot repeats bounded action cycles. It should keep solving one concrete problem after another until the goal is done, blocked, or a configured limit stops the run.

Autopilot Bounds

  • Cycle count limits prevent open-ended runs.
  • Retry limits prevent repeated failures from looping forever.
  • Provider timeout settings prevent long-running calls from blocking unattended operation.

Completion

Completion creates a handoff package under .workjinn\85_Completion. It can include deterministic evidence, current status, and optional provider review.


Providers

Provider settings visual
Provider settings define which AI and tool routes WorkJinn may use for each stage.

Providers are configured in the settings area and stored in local configuration. Routes decide which provider handles each stage.

Provider Roles

Provider | Typical Role
LM Studio | Preferred local AI route for private chat, planning, review, and workflow analysis.
DeepSeek | Cloud AI route for users who configure their own endpoint and API key.
Local tool provider | File and command execution lane when a task needs real changes or command output.
Command-line AI providers | Optional worker routes for users who have those tools installed and configured.
OpenAI Transcribe | Audio transcription route. Real secrets must come from environment or local settings, not repo files.

Routing

Routes can be explicit or automatic. Automatic local routing favors configured local providers and records fallback reasons in logs and route summaries.

A provider being reachable is not the same as being ready for a full workflow. For file changes, command runs, tests, and project evidence, WorkJinn also needs a working tool lane and clear review criteria.

Small Model Safeguards

The Settings form can enable Answer Guard and Better Prompt. Answer Guard asks the provider to decide whether a response fits the original prompt and can retry with an improved prompt. Better Prompt rewrites a prompt before sending it to the provider, using modes such as FOCUSED, STRICT, or STEPWISE.

Security Notes

  • Do not store real API keys in repository files.
  • For cloud providers, use environment variables or local settings. Do not ship a real key.
  • Review provider output before trusting generated changes.
  • Tool execution should be treated as a privileged action and reviewed through logs and evidence.


Local AI Supervision and Quality Gates

Local AI supervision visual
Local AI supervision keeps model output tied to concrete checks, files, and review evidence.

WorkJinn can run with local AI through LM Studio and with local tools through a configured tool connection. Local models are useful, private, and fast enough for many workflows, but they need clear supervision.

Recommended Local Lane

  1. Use LM Studio as the reasoning provider.
  2. Enable the local tool connection when the task needs file or command actions.
  3. Require concrete files, command results, and evidence paths.
  4. Run a supervisor audit after each cycle.
  5. Enable Answer Guard or Better Prompt when the loaded local model is small or inconsistent.
  6. Repair prompts instead of accepting weak evidence.

Common Local Model Failures

  • Tool-plan markers can leak into generated files.
  • File names can drift away from the requested names.
  • Shell scripts can pass accidentally or fail before testing the real target.
  • C and batch escaping can be corrupted by small models.
  • Review can pass based only on file existence unless acceptance rules are concrete.

Supervisor Checklist

  • Check the target root for required files.
  • Search root deliverables for ToolPlan markers, double angle brackets, or end-action text.
  • Run the generated verification or test step independently when one exists.
  • Read WorkJinn cycle review and validation files, but do not trust them alone.
  • Use repair cycles for marker leakage, wrong paths, stale logs, or weak evidence.
  • Run Completion only after the target project is clean enough for handoff.

Built-In Quality Gates

Local models can fail by returning vague instructions, wrong file names, or unsafe command ideas. WorkJinn uses built-in quality gates for common task shapes. These gates do not replace the provider; they keep the workflow grounded in files, visible outputs, and reviewable evidence.

Task lane | Gate output
Book | Clean chapter files plus continuity sidecar; manuscript files are checked for tool-marker contamination.
Existing Code | Sidecar baseline under .workjinn: tree, run capture, evidence standard, and baseline report.
New Code From Plan | Starter scaffold, README, implementation note, and run notes.
Plan Then Code | Implementation plan, starter files, run template, and verification notes.
Prompt Discovery | Prompt analysis, verification template, and dry-run log.
File Set | Baseline report and evidence capture before changing targeted files.
Bug Fix | Reproduction log, regression wrapper, and structured evidence file.
Add Tests | Coverage report, prioritized gap list, source inventory, and test evidence.
Write Docs | README, draft sidecar, progress metadata, and verification log.

Prompt Rules That Help

  • Keep required file lists short and exact.
  • Use explicit expected outputs.
  • For local GUI projects, require no CDN, no network, and root-relative files.
  • For legacy source formats, require the expected line endings, encoding, and short generated lines.
  • For C, prefer simple output and avoid fragile escape-heavy code when using small models.
  • For batch files, avoid subroutine labels unless absolutely needed.

Answer Guard and Better Prompt

Answer Guard is a defensive retry loop for weak local models. WorkJinn asks the provider whether the answer is valid for the original prompt and expects a clear YES or NO style verdict. When the verdict is NO, WorkJinn can use the improved prompt from the guard response and retry within the configured limit.

Better Prompt runs before the main provider call. It rewrites the prompt to be more explicit, focused, and testable. Use it when a model often misses exact file names, required sections, or acceptance details.

Completion Criteria

A WorkJinn project is ready when the target files exist, user-facing files are free of tool-plan markers, verification checks pass when present, the review decision is SUBGOAL_DONE or GOAL_DONE, and Completion writes a final evidence index.


QuickStart Options Reference

QuickStart options visual
QuickStart options choose the task shape before WorkJinn creates or adopts the project workspace.

QuickStart is the fastest way to start a WorkJinn-controlled project. It asks for a provider, a project folder, and a prompt, then seeds the workflow with task-specific defaults.

Common Rules

  • Provider: choose the local AI route for private local work. LM Studio is the preferred local planning provider.
  • Project Folder: choose a new folder for a new project or an existing folder for adoption and sidecar work.
  • Prompt: describe the final result and acceptance evidence. WorkJinn stores the prompt with the project trail.
  • Tool connection: when enabled, LM Studio plans the work and WorkJinn executes file and command actions through the configured local tool lane.

Write a Book

Creates a writing project with manuscript files, outline, drafting evidence, and revision checkpoints. Use this when the output is prose, chapters, or a structured publication.

Chapter files should remain reader-facing manuscript text only. Continuity notes, tool evidence, and next-chapter setup belong in the WorkJinn sidecar, not at the end of chapter files.

When a book already has chapter files, later cycles continue from the existing manuscript and continuity sidecar. WorkJinn should not restart with a new premise after Chapter 1; it creates the next missing chapter subgoal and keeps going until the planned chapter set is complete.

Work on Existing Code

Adopts an existing source tree in sidecar mode, records the target, and prepares a continuation workflow. WorkJinn should preserve existing behavior and make one verified change at a time.

The first live cycle now records a sidecar baseline: project tree, run capture, evidence standard, and baseline report under .workjinn.

Create Code from Existing Plan

Starts from a plan or specification and converts it into implementation stages. Use this when the desired architecture and features are already known.

The first live cycle creates starter files, a README, implementation notes, and run guidance. If the local model creates only partial scaffolding, WorkJinn uses the requested task context to keep the first result reviewable.

Create Plan, Then Code

Starts from a rough idea. WorkJinn first turns the idea into an executable plan, then moves into implementation cycles with evidence.

The first live cycle creates an implementation plan, starter files, a run template, and verification notes before moving into the implementation phase.

Develop from Prompt, Step-by-Step

Use this when the request is vague or exploratory. WorkJinn discovers the shape of the work, writes the first concrete plan, then iterates from evidence.

The first live cycle now creates ANALYSIS.md, VERIFY_TEMPLATE.md, and a dry-run log so broad prompts are turned into reviewable project facts.

Work on a Set of Files

Focuses the task on selected files or a bounded component. This is useful for cleanup, refactoring, documentation edits, and narrowly scoped feature work.

Fix a Bug

Drives a defect from reproduction through diagnosis, patch, and regression evidence. The prompt should include observed behavior, expected behavior, and any failing command or log.

Add Tests

Audits coverage and adds high-value tests. The best prompts identify the risk surface, expected test command, and what must fail before the fix or pass after the change.

Write Documentation

Creates or updates practical documentation: README, usage notes, command references, architecture notes, and handoff material.

The first live cycle can deterministically produce README content, a draft sidecar, progress metadata, and a verification log when the provider cannot produce a safe ToolPlan.

Local AI Quality Notes

Small local models can produce plausible text while missing exact syntax, file names, or internal planning markers. Use precise success rules, short required file lists, and supervisor checks. If a generated file contains internal marker text, run a repair cycle before accepting the project.


Command-Line Options

Command-line operation visual
Command-line runs use the same WorkJinn stages and evidence model as the GUI.

WorkJinn can be run from the GUI or from the command line. Most users should start with the GUI. The command line is useful for repeatable project runs, scheduled checks, and advanced automation.

Core Stage Options

  • --stage goal: run goal definition.
  • --stage elaboration: run goal elaboration.
  • --stage experts: prepare or refresh the expert board.
  • --stage discussion: run board discussion.
  • --stage execution: execute the current work order.
  • --stage testing: run validation.
  • --stage review: run board review.
  • --stage cycle: run one complete action cycle.
  • --stage autopilot: run bounded repeated cycles.
  • --stage completion: write the final handoff package.
  • --stage all: run setup and the first cycle path.

Project Options

  • --project name: use or create a WorkJinn project by name.
  • --project-folder path: use an explicit target folder.
  • --adopt-folder path: adopt an existing project in sidecar mode.
  • --adopt-auto-root: infer the project root while adopting.
  • --adopt-then stage: adopt and immediately run a stage.
  • --raw-file path, --elab-file path, --cycle-file path: seed stages from files.
  • --raw-text text: seed the raw goal from command text.
  • --approve: approve seeded goal and elaboration when the workflow allows it.

Provider Options

  • --definition-provider, --elaboration-provider, --expert-board-provider: choose providers for planning stages.
  • --discussion-provider, --execution-provider, --testing-provider, --review-provider: choose providers for action cycle stages.
  • --completion-provider: choose the provider for completion review.
  • --require-live: fail when a required live provider is not available.
  • --provider-timeout, --execution-timeout, --autopilot-cycle-timeout: set bounded timeouts in seconds.
  • --answer-guard, --no-answer-guard: enable or disable response self-checking for small models.
  • --prompt-refiner, --no-prompt-refiner: enable or disable prompt preprocessing.
  • --prompt-refiner-mode: choose a prompt refinement mode, for example FOCUSED, STRICT, or STEPWISE.
  • --better-prompt, --no-better-prompt, --better-prompt-mode: aliases for the prompt refiner options.

Tool Options

  • --tool-bridge sindbyte-mcp: enable the local tool execution lane.
  • --tool-bridge off: disable the tool execution lane.
  • --mcp-url: set the local tool endpoint when you use a custom setup.
  • --tool-bridge-key-provider: choose which provider supplies the key source for tool calls.
  • --max-tool-passes: cap repair/execution passes.
  • --max-actions-per-plan: cap actions per tool plan.

Task Wizard Options

  • --task book: create a book project.
  • --task existing-code: adopt or continue an existing code project.
  • --task new-code-plan: implement from a plan file.
  • --task plan-then-code: plan from an idea and then implement.
  • --task prompt: discover project shape from a free prompt.
  • --task file-set: focus on selected files.
  • --task bug-fix: reproduce, repair, and prove a bug fix.
  • --task add-tests: add or improve tests.
  • --task write-docs: create documentation.
  • --title, --author, --genre, --chapters, --word-count: book-specific fields.
  • --folder: target folder for existing-code, bug-fix, add-tests, and docs tasks.
  • --description: plain task description.
  • --plan-file: plan source for new-code-plan.
  • --lang: target language hint.
  • --prompt: prompt-discovery source text.
  • --name: project name.
  • --output-folder: project output root.
  • --auto-run: run after wizard creation.
  • --task-dry-run: create wizard state without running the dashboard.

Reports and Diagnostics

  • --option-report: write option and command coverage information.
  • --route-report: write provider route diagnostics.
  • --provider-acceptance: run a provider readiness check.
  • --delivery-check: run a local readiness check.
  • --smoke all: run built-in self checks.
  • --cli-test: test GUI command surfaces through the CLI harness.
  • --target-folder: target folder for CLI and UI readiness tests.


Feature Reference

Feature reference visual
This reference explains what each major WorkJinn area is for and when to use it.

Use this page as a quick end-user reference when you know what you want to do but are not sure which WorkJinn area owns it.

Startup and project setup

Feature | Use it for
Choose Your Task | Selecting the kind of work: book, existing code, new code, bug fix, tests, documentation, prompt discovery, or file-set work.
Quick Start | Entering the minimum provider, folder, and prompt details needed to begin.
Project adoption | Working on an existing folder while keeping WorkJinn state in a sidecar folder.
New project | Creating a clean WorkJinn-managed workspace for a new goal.

Planning and review

Feature | Use it for
Goal Definition | Turning a rough request into a clear goal with enough context to act on.
Goal Elaboration | Breaking the goal into concrete work, constraints, success criteria, and evidence expectations.
Experts | Choosing the perspectives that should review plans and results.
Action Cycle Review | Deciding whether to retry, improve, accept a subgoal, complete the whole goal, or stop as blocked.

Doing work

Feature | Use it for
Action Cycle | Running one complete discussion, work-order, execution, validation, and review pass.
Autopilot | Repeating action cycles with safety limits until the work is done, blocked, or timed out.
Batch Lab | Applying review, cleanup, transformation, or merge steps across a controlled set of files.
Completion | Creating the final handoff package after the project is ready.

Provider and safety features

Feature | Use it for
Provider settings | Choosing which AI or tool route handles each stage.
Model refresh | Updating the visible model list for compatible providers.
Provider test | Checking whether a provider responds before starting a large task.
Tool connection test | Checking whether local file and command actions are available when a task needs them.
Timeouts | Preventing a busy or unresponsive provider from blocking forever.
Answer Guard | Adding an extra self-check when a model often gives incomplete answers.
Better Prompt | Rewriting a vague prompt into a more direct prompt before it is sent to the provider.

Book-writing features

Feature | Use it for
Book task | Creating a book workspace with chapter files, continuity notes, and writing goals.
Recover Book Project | Continuing a book that already has chapter files or a WorkJinn sidecar.
Quality criteria | Choosing which chapter problems must force a correction pass.
Continuity sidecar | Keeping planning, continuity, and review notes out of reader-facing chapter text.


Logs and Troubleshooting

Logs and troubleshooting visual
Logs and troubleshooting pages point to the evidence needed to understand provider and workflow behavior.

Important Logs

Path | Use
Application log | GUI startup, task selector, Quick Start, adoption, provider route, and handoff messages.
Provider log | Last provider run, endpoint response, and route information where available.
Cycle log | Last cycle status, final decision, and stage summary.
<target>\.workjinn\90_Logs | Project-local evidence and workflow logs.

Common Checks

  • If the app exits after Quick Start, inspect the application log around the last adoption or progress-dialog entry.
  • If a provider does not appear usable, run provider settings validation and check route fallback messages.
  • If a cycle does not finish, check the final decision first. It normally explains whether the run was done, blocked, timed out, or waiting for better evidence.


Troubleshooting

Most WorkJinn failures can be diagnosed from the stage, provider route, cycle state, and evidence files.

Provider unreachable

  • Verify that the local endpoint is running.
  • Check provider settings, API key source, selected model, and base URL.
  • Run a small provider probe before a large project cycle.
  • For LM Studio, confirm the model is loaded and the local server is enabled.

Exit code is 0 but no work was accepted

  • Open the latest cycle review verdict; a successful process can still produce RETRY.
  • Open Logs and inspect the latest cycle and provider summaries.
  • Check the target .workjinn folder for execution, validation, and review artifacts.
  • Look for missing required files, wrong paths, or weak evidence in the execution result.

Generated files contain tool-plan markers

  • Reject the cycle or run a repair cycle.
  • Search for <<Action, <<EndAction, YAML/frontmatter, and hidden metadata in user-facing files.
  • For book projects, chapter files must contain only reader-facing manuscript text.

Stale autopilot lock

If the dashboard finds an Autopilot lock, WorkJinn asks whether the lock should be cleared. Choose No when another WorkJinn window is still working on the same project. Choose Yes only when no active run should own that project lock; WorkJinn clears it and starts the cycle again.

CLI users can still clear a stale lock with --force-clear-autopilot-lock after checking that no run is active for the project.

Missing evidence files

  • Confirm write permissions for the target folder.
  • Increase provider and execution timeouts for slow local models.
  • Use deterministic task gates where available: book, existing-code, new-code-plan, plan-then-code, prompt, file-set, bug-fix, add-tests, and write-docs.
  • Review produced_artifacts.md, commands.md, and errors.md for the current cycle.

Source or command verification fails

  • Open the verification output created by the project or cycle.
  • Check whether generated files use the required line endings, encoding, and file names for that project.
  • If the model produced malformed code or command text, run a correction pass instead of accepting the result.

Escalation checklist

  1. Record command, timestamp, provider, model, task type, and project folder.
  2. Attach the latest WorkJinn log and the target cycle folder.
  3. State the last review decision and active subgoal.
  4. List expected files versus actual files.


FAQ

WorkJinn FAQ visual
Short answers for common WorkJinn operating questions.

Is WorkJinn a GUI-only tool?

No. The GUI is primary for setup and visual control, but command-line stages are also available for repeatable runs and advanced automation.

Can WorkJinn keep working on a large project?

Yes. WorkJinn is built around bounded cycles, project-local state, expert boards, validation, review decisions, and completion artifacts. This reduces dependence on one long provider conversation.

Why can WorkJinn use less context than a normal CLI chat?

WorkJinn splits work into smaller prompts and persistent artifacts. The provider sees the current goal, current subgoal, work order, and evidence instead of relying on an ever-growing chat history. This lowers drift and helps smaller local models stay on task.

Can I use only one local provider?

Yes. Stage routing lets you force LM Studio or another configured provider for every stage during verification. Mixed routes are also possible when one provider is better for planning and another is better for execution or review.

Can I interrupt and resume later?

Yes. Resume from the project folder and its .workjinn sidecar. Check the current cycle state, last decision, logs, and evidence before continuing.

Where are logs?

Open Logs from the dashboard. Project evidence and cycle artifacts are also stored under the target project folder or its .workjinn sidecar.

Does WorkJinn modify existing code during adoption?

Existing-code adoption uses sidecar mode. The first baseline cycle should write WorkJinn artifacts under .workjinn and preserve source files until an explicit execution subgoal asks for changes.

What should I do if a local model creates weak output?

Use the review result, rerun the cycle, or switch to a more capable provider/model. Current LM Studio lanes also include deterministic first-cycle gates for common weak ToolPlan cases.

Can it run on non-Windows machines?

The current application is Windows-first. Paths, help, and local tool assumptions are Windows-oriented.


Copyright, Legal, and AI Use

Legal and AI use visual
Legal and AI-use notes help keep generated project work reviewable and properly governed.

This page is intentionally separate from the usage manual. It summarizes legal and operational cautions for WorkJinn users. It is not legal advice.

Copyright

Copyright (c) 2026 Theo Gottwald unless a different notice is present in a specific file or bundled component.

Owner | Theo Gottwald
Profile | Leading Expert in SPR & Visual Automation
Address | Herrenstr. 11, 76706 Dettenheim
Telephone | (07247) 9851112
Fax | (07247) 9851113
Mobile | 0160 - 66 88 222
E-Mail | theo.gottwald@it-berater.org
Web | it-berater.org
X | https://x.com/TheoGottwald
Explore More | smart-package.com
Smart AI Robot | https://smart-ai-robot.com

WorkJinn helps create project artifacts, prompts, reviews, source changes, summaries, and handoff packages. The user or organization operating WorkJinn is responsible for determining ownership, licensing, attribution, and reuse rights for all generated and edited material.

Txt2Book Utility

The WorkJinn package includes Txt2Book.exe as a companion utility program. Txt2Book is copyrighted by Theo Gottwald and may be used free of charge for private, non-commercial use. Redistribution, commercial use, resale, or repackaging require separate permission from the copyright holder.

Third-Party Components

WorkJinn may use or interoperate with third-party tools, services, models, and local runtimes. Their names, trademarks, binaries, SDKs, and APIs remain the property of their respective owners.

AI Output

AI-generated analysis, plans, code, documentation, and review output must be inspected before use. WorkJinn records evidence and logs, but it does not guarantee correctness, security, legal compliance, or fitness for production.

Generated output can be incomplete, wrong, unsafe, misleading, or incompatible with a target license. Treat generated text, code, shell commands, test plans, legal wording, and documentation as draft material until reviewed by a qualified human and verified with the project's normal acceptance process.

Third-Party Input

Do not feed WorkJinn code, documents, datasets, credentials, client material, or other content unless you have the right to process it with the selected provider. Provider choice matters because local and remote providers can have different data-handling terms.

Provider Terms

Providers such as LM Studio, OpenAI, Codex, OpenCode, Kimi, and SindByte can have separate licenses, terms of service, privacy policies, quotas, and safety limits. Review those terms before using a provider for confidential, commercial, regulated, or customer data.

Secrets and Data

  • Do not store real API keys, passwords, or private tokens in repository files.
  • Check target project confidentiality before sending prompts to external services.
  • Keep provider logs and generated artifacts under appropriate access controls.

Open Source and License Compliance

When WorkJinn edits or generates code that incorporates existing projects, dependencies, snippets, or generated suggestions, the user remains responsible for checking license compatibility, notices, attribution, copyleft obligations, export restrictions, and redistribution rules.

Professional Domains

Output related to legal, medical, financial, safety-critical, security-sensitive, or regulated domains requires review by appropriately qualified professionals. WorkJinn does not replace professional judgment.

Security and Command Execution

WorkJinn can prepare commands, tool calls, and project changes. Review commands before running them in sensitive environments. Keep backups and do not execute destructive actions unless the target, scope, and rollback path are clear.

Screenshots and Logs

Screenshots and logs can expose paths, user names, project names, prompts, model names, API endpoints, and private data. Review them before sharing outside the local machine or organization.

No Legal Advice

This help file is operational documentation, not legal advice. Review licensing, privacy, export, employment, customer, and regulatory obligations with qualified counsel where needed.

Warranty Disclaimer

WorkJinn is provided as-is unless a separate written agreement states otherwise. Use it at your own risk and validate generated work before relying on it.