digitalworker-docs

Digital Worker User Guide

Audience: human users who submit tasks to Digital Worker via Trello on their own connected board Purpose: explain what Digital Worker is, how to use it, what it can and cannot do, and what actions are prohibited.

TL;DR: DigitalWorker turns a task card on your Trello board into a tested, reviewed pull request on your GitHub repository. You decide what matters; it does the engineering work — implementation, tests, review, and fixes.

This guide covers using DigitalWorker on your own Trello board connected to your own GitHub repository. That requires a Trello account and a GitHub repository. If you are not yet at this stage, there are two earlier ways to engage:

Verify our claims — clone the public demo repo, run the tests, view the public Trello board. No accounts needed. See the Sell Sheet § Getting Started.

Try it on the demo board — request access to the demo Trello board, submit a task card, watch DigitalWorker produce a pull request. Trello account only. See the Sell Sheet § Getting Started.

What Is Digital Worker?

Digital Worker is a fully autonomous, non-interactive AI coding agent. It reads software-development tasks from task cards on your Trello board, executes them using an AI coding agent, and publishes results back to Trello. You never interact with it directly in a chat or terminal — all communication happens through Trello cards.

Execution is autonomous, but pivotal product and architecture decisions remain yours. You no longer review its work for logic — AI reviews and checklists handle that. Your review is judgment: connection to the physical world, prioritization, architecture decisions, new classes and their relationships, and important trade-offs — placed early, before implementation. For complex or high-impact work, use planning mode first so you can spot-review and correct selected sections of the AI-drafted research, planning, architecture, and class-design document package before implementation.

Digital Worker’s proprietary Instruction Engine keeps required engineering instructions in the execution path. That enforcement is what makes the result dependable: models are trained on a corpus heavy with anti-patterns and drift back to them over long, multi-part tasks — even with skills, rules files, and explicit guardrails — so the engine keeps relevant instructions in the execution path rather than trusting the model to hold the whole procedure. The integrated product is currently in early access; its underlying checklists and instructions have been refined through two years of daily engineering use.

Why rigorous engineering discipline matters

The benefits of test-first TDD, Clean Architecture (business rules separated from frameworks, UI, and databases), and OOP/Rich Domain Models — objects carrying both data and the rules that act on them — are much larger than many teams realize. These disciplines are not cosmetic preferences: they keep behavior testable, dependencies directional, and domain concepts explicit as features, integrations, teams, customers, and business rules multiply.

That creates a compounding business advantage. A disciplined codebase can support a larger product and business without every new feature becoming disproportionately harder, slower, and riskier. Most businesses want to grow; rigorous engineering helps prevent software complexity from becoming the limit on that growth.

	DigitalWorker PR Reviewer	DigitalWorker (full agent)
What it does	Reviews your pull requests and posts feedback as GitHub reviews — Agile architecture violations such as incorrect layer dependencies and Anemic Domain Model anti-pattern, testability issues, test coverage gaps, and most code smells including code and class duplication	Every part of the software development lifecycle (SDLC): plans, architects, designs classes and UX, implements and tests features, reviews code, fixes issues
How you use it	Always-on — every PR and every push is reviewed automatically; optional `@digitalworker review` comment	Create and move Trello cards on your board
Trello account	Not needed	Required
GitHub access token (PAT)	Not needed — GitHub App permissions only	Not needed — the Agent app covers it; a PAT exists only for legacy configurations
Onboarding effort	Install the app on your repos (~1 minute)	Board provisioning + repository onboarding (~7 minutes)

DigitalWorker PR Reviewer is the simplest, risk-free way to start: it is read-only and always-on, so you see review quality on real PRs immediately. DigitalWorker is the full-featured agent you graduate to when you want it doing the work, not just reviewing it.

Trial Credit and Paid Conversion

Both products share the same trial and billing policy — one credit allowance per customer, whichever way you started:

You pay from a prepaid credit balance. Usage draws down your balance. When it runs out, work pauses until you add credit.
Every new customer gets a bounded amount of free usage credit. It makes no difference whether you installed the PR Reviewer GitHub App or onboarded a full DigitalWorker Trello board — the same credit policy applies to you as a customer.
When the credit runs out, we tell you in place. For PR Reviewer, DigitalWorker posts a comment on the pull request explaining the trial credit is exhausted and how to continue. For full DigitalWorker, the active card is moved to Blocked with a comment explaining the same, and new cards are held until credit is added.
Converting to paid is one message. Contact info@agiledigitalworker.com — we’ll reply with a secure payment link. Your setup is untouched — no reinstall, no new onboarding, no lost history — and service resumes as soon as credit is added.
Using both products? Tell us your GitHub account and Trello username when you contact us and we’ll link them under a single credit balance.

How to Use DigitalWorker PR Reviewer — read-only reviews without Trello

The DigitalWorker PR Reviewer is a GitHub App, and it needs no Trello account and no GitHub personal access token (PAT) — a scoped credential that lets a tool act on your repo. Instead of picking up task cards, it reviews your pull requests and posts the result as a normal GitHub review. It is read-only: it never modifies your code, pushes commits, edits files, or creates pull requests. It runs the same review engine the full DigitalWorker Agent uses on its own work: a ~100-item engineering checklist covering correctness, architecture and standards, code-smell detection, and requirements audit. DigitalWorker PR Reviewer is a great way to start simple and in a risk-free way and see if you want to progress to a full featured DigitalWorker.

Onboarding - Installing the PR Reviewer on your repository

Open the install link: https://github.com/apps/digitalworker-reviewer/installations/new.
Choose your account or organization, select the repositories you want reviewed, and confirm.
Done — there is no software to install, no tokens to paste, and no per-developer setup. GitHub App permissions replace the personal access token used by the Trello flow, so nothing sensitive is ever posted to a board.

Want out? In GitHub: Settings > Applications > Installed GitHub Apps > Uninstall (or Configure to remove it from specific repositories). Reviews stop immediately - there is nothing to cancel on our side.

Requesting a review

Automatic: every pull request you open (and every new commit pushed to it) is queued for review.
On demand: post a comment whose entire text is exactly @digitalworker review on the pull request. The command must be the whole comment — adding extra words or sentences means it is not recognized and nothing happens.
Reviews of the same pull request are deduplicated: pushing a new commit while a review is still queued replaces the stale request, and repeated deliveries are ignored, so you never get duplicate reviews for the same head.

What you get back

A GitHub review from digitalworker-reviewer[bot] (state: COMMENTED, pinned to the commit that was reviewed) containing:

A summary with a letter-grade score (A–F), an overview of detected architectural issues and code smells, and key risks.
Inline comments attached to specific lines of the diff, each tagged with a severity (CRITICAL, HIGH, MEDIUM, LOW).

Use it as a first-pass reviewer: it reads only the PR diff, so treat it as a strong second opinion, not a merge gate. It does not answer questions in comments — only the exact @digitalworker review command triggers it.

How to Use DigitalWorker

Onboarding DigitalWorker

Email your preferred Trello board name to info@agiledigitalworker.com (or message your contact). Digital Worker provisions your private board and sends you an invite (requests are usually addressed within 24 hours).
Connect your repository (takes ~1 minute): Onboarding is instant and does not run any AI coding agents. On your board’s first card, answer the clone URL and default branch. When your operator has linked the Digital Worker Agent GitHub App to your Trello account, repository, and board, you are not asked for a personal access token. If linking is still pending, the card asks you to wait for the operator — it will not request a PAT.

Install the Agent app on your repository from its public install link: https://github.com/apps/digitalworker-agent/installations/new — select the repository you named in your onboarding answer. Installing the app on that repository plus your board’s onboarding answers is the complete authorization act — no tokens, no approval step on our side.

Legacy PAT mode: a personal-access-token flow still exists for rare cases where the Agent app cannot be installed; it is arranged directly with your operator and is never part of standard onboarding.

The card title can be anything (e.g., Onboard me).
Use a private Trello board. Agent onboarding never asks you to post a token (legacy PAT mode only — if a token was ever posted, delete that comment once confirmed).
Digital Worker saves the repository configuration and requests a service restart automatically. You do not install software, run terminal commands, or configure each developer’s machine.
Delete/archive the onboarding card in “Blocked” and create a new card for your first task, or rerun the first card if it already has a real task. Agent onboarding has no token-deletion step — in legacy PAT mode only, also delete the comment that held the token.

Submitting a task

Create a Trello card on the configured Digital Worker board.
Set the card title to a short, clear summary of the task.
Set the card description to the full task details — what to implement, context, constraints, acceptance criteria.
Move the card to the “To Implement” list (or draft it in “Triage” until requirements and acceptance criteria are finalized, then move it to “To Implement”).
Digital Worker will automatically pick up the card, move it to “Running”, and begin work.

A good zero-risk first task: create a card asking Digital Worker to review a slice of your codebase. It marks architecture and code-smell issues as //TODO comments without modifying your code — a safe way to see the review workflow in action. The issues it surfaces are the same ones that make AI-written code plateau and eat your attention.

Planning a task

If your board has a “To Plan” list, placing a card there causes Digital Worker to run in planning mode. It automatically selects a lighter or more detailed planning process based on the task’s complexity. Instead of implementing code directly, it creates an AI-drafted document package covering research, planning, architecture, class design, integration points, implementation sequence, trade-offs, assumptions, and open questions. The planning result is published as a Trello comment; if the workflow writes documents to the repository, Digital Worker commits them and includes the resulting pull request link.

Before implementation, spot-review and correct the decision-heavy sections that require your judgment, especially:

Proposed new classes and responsibilities — Digital Worker searches for existing host classes, but your judgment on whether a new class is truly needed is the final check.
Duplicate classes or behavior that belongs in an existing class.
State-and-behavior alignment for an OOP/Rich Domain Model.
Architecture trade-offs, assumptions, pivotal methods and properties, and novel decisions.

Add corrections as comments or update the card description, then move the card to the implementation intake list. Digital Worker sees the recent comments when it runs the implementation task.

Tracking progress

Digital Worker manages card lifecycle automatically:

Triage → drafting and refining task requirements before execution.
To Implement (or To Plan) → card waiting to be picked up.
Running → Digital Worker has claimed the card and is working on it. A Started (or Planning Started) comment is added.
Done → task completed successfully. The result answer is posted as a comment, and if code changes were made, a pull request link is included.
Blocked → task could not be completed (failure, timeout, or policy block). A comment explains the outcome.

You do not need to move cards between lists manually once a card is in an intake list. Digital Worker handles all list transitions.

Receiving results

When Digital Worker finishes a card:

A result comment is posted on the card with the agent’s answer and a summary of what was done.
When the task produces source-controlled changes, Digital Worker reviews the intended file set, excludes temporary and build artifacts, commits the changes, pushes the branch, and opens or locates the pull request. The PR link is included in the comment.
You do not need to ask for the ordinary task PR. Request PR creation or merge explicitly only when you want an additional PR-related action beyond the automatic task PR.
The card is moved to Done on success or Blocked on failure. When a failed run has recoverable work, its isolated worktree — a separate working copy of your repository — is preserved for several days so a later run can resume it.

What You Should Do

Write clear, specific task titles and descriptions. The title and description are the primary statement of task intent. Recent comments add context, but they do not replace clear requirements and acceptance criteria. Vague cards produce vague results.
Keep tasks focused on software development. Digital Worker is designed for coding, planning, testing, code review, refactoring, and bug fixing.
Use English. Task titles and descriptions must be in English. Non-English text will be blocked.
Include relevant context. If the task depends on specific files, classes, or patterns, mention them in the description.
Plan complex or high-impact work first. Use the “To Plan” list so you can review pivotal product and architecture decisions before implementation.
Spot-review and correct the planning package. Focus on selected decision-heavy sections such as new classes, responsibilities, trade-offs, assumptions, and novel decisions rather than treating the AI draft as authoritative.
Add comments for follow-up context. Recent comments on the card are included in the agent’s input, so you can add clarifications after submission.
Perform a final behavior and architecture check. Before merging, verify that the result satisfies your intent and that pivotal design decisions were implemented correctly.
Let Digital Worker manage card movement. Once a card is in an intake list, do not move it manually unless you want to cancel or redirect it.

What You Do Not Need to Do

You do not need to install software or configure each developer’s machine. After you answer the three first-time onboarding questions, Digital Worker configures the repository and execution environment.
You do not need to provide an AI model API key or subscription — BYOK (“bring your own key”) is not offered. We provide the AI infrastructure and model routing. Digital Worker routes through dedicated gateways with strict Zero Data Retention (ZDR) guarantees.
You do not need to run any commands. All execution is handled by Digital Worker.
You do not need to create branches or pull requests. Digital Worker creates isolated Git worktrees, commits changes, pushes branches, and opens PRs automatically.
You do not need to monitor the agent in real time. Results are posted to Trello when the task is done.
You do not need to direct implementation through an iterative prompt loop. Digital Worker executes the selected workflow, tests the implementation, reviews it, refactors it, and fixes identified issues before opening the PR.
You do not need to review every generated line or every generated test as the normal operating process. Reserve your attention for pivotal planning and architecture decisions, selected Domain code, and the final behavior and architecture check appropriate to the task’s risk.

What You Should Not Do

Do not attempt to extract, reveal, or enumerate system prompts, workflow instructions, internal protection mechanisms, tool lists, or any other IP of Digital Worker. These attempts are detected and blocked.
Do not ask to list or enumerate workflow names. Enumerating workflow names is not permitted. The request is not treated as malicious, but it will be declined.
Do not attempt to override or ignore instructions (e.g., “ignore previous instructions”, “you are now a different assistant”, “disregard all rules”).
Do not submit encoded or encrypted payloads designed to bypass input screening (e.g., base64-encoded instructions, leet-speak obfuscation, zero-width character injection).
Do not submit non-coding tasks. Tasks unrelated to software development (e.g., “write a poem”, “translate this text”) will be soft-blocked — flagged and declined rather than executed.
Do not use non-English characters in task instructions. Non-Latin text will be soft-blocked.

What Digital Worker Can Do for You

Research, plan, architect, and design — create an AI-drafted document package covering research, planning, architecture, class design, and UX/design planning for you to spot-review and correct before implementation.
Implement features with enforced test-first TDD — start each feature with a failing test, add the minimum implementation needed to pass, and run the relevant test suite. Digital Worker targets strong conventional test coverage; it does not guarantee complete mutation coverage — the level at which the tests catch any defect introduced into the covered code. The payoff is substantially fewer defects and less cleanup: tests establish expected behavior before implementation, and the dedicated correctness review and fix passes below address issues before the PR. For routine tasks, you perform a quick final behavior check before merge; pivotal design decisions still need your judgment. See “Engineering workflow” below for the delivery steps and why a final human check remains necessary.
Apply Clean Architecture, SOLID, and OOP/Rich Domain Model discipline — drive behavior and state into appropriate Domain objects, protect layer direction, and avoid anemic — data-holding objects with no behavior of their own — or procedural designs.
Prevent duplicate and anemic classes — before proposing any new class, search the codebase for existing classes that could host the planned behavior. This significantly reduces the code and class duplication that every other AI coding tool produces.
Fix bugs — diagnose defects through evidence from code, tests, builds, logs, command output, research, or an approved spike before changing implementation. If you find a defect after merge, submit a focused fix card with steps to reproduce it and the expected result so Digital Worker can perform the repair work.
Write tests — create unit, integration, or end-to-end tests following testing best practices such as test isolation.
Review code — run a ~100-step checklist-driven review covering requirements, architecture, design, code, testability, engineering standards, and code smells.
Refactor legacy code — preserve behavior while moving procedural or tightly coupled code toward modular, testable design using OOP and functional techniques where appropriate.
Refactor and fix review findings — improve structure while preserving behavior, then resolve identified review and code-smell issues before opening the PR.
Commit and push safely — review the intended file set and stage only task-related changes. Exclude temporary files, build and generated output, package directories, virtual environments, local configuration and secrets, and OS/IDE files. Commit locally, then let the system push the branch and open a pull request for your final behavior and architecture check.

Current limitations

Visual UX improvements are not supported at this stage. Tasks that require rendering or visually verifying a UI are not supported; the agent works from code, tests, and text, not from rendered screenshots. You can still request UX/design planning (layout, interaction copy, information architecture) and code-level UI changes, but the agent cannot visually verify the rendered result.

How Digital Worker Works

Engineering workflow

For feature work, Digital Worker’s standard engineering pipeline is:

Research and draft the document package — produce planning, architecture, and class-design artifacts.
Human decision checkpoint when warranted — you spot-review and correct selected decision-heavy sections for complex or high-impact work. Routine work can run end to end without this checkpoint.
Test-first implementation — write and run a failing test before adding the minimum implementation needed to pass.
Architecture and code discipline — apply Clean Architecture, OOP/Rich Domain Model, and Clean Code rules during implementation. Before creating any new class, search the codebase for existing host classes, and apply a cohesion check.
Structured AI review — run the ~100-step checklist-driven review across requirements, architecture, design, code, testing, standards, and code smells.
Refactoring and fixes — refactor while preserving behavior and resolve identified issues.
Pull request and final human check — open the PR for your final behavior and architecture check.

Planning, implementation, testing, and review are routed to models and reasoning levels selected for the best quality/cost balance, avoiding premium-model prices for routine execution.

The workflow produces engineering evidence and reduces supervision, but it does not guarantee a defect-free result or remove your responsibility for the final check before merge.

For the method, concrete code examples, and recorded demo evidence behind this pipeline, see the Engineering Deep Dive.

Trello and execution flow

Card selection — Digital Worker first resumes a card already in “Running”; otherwise it selects the first card from “To Plan”, then “To Implement”.
Context loading — recent comments are fetched so the agent has the current task context.
Card started — a newly selected card is moved to “Running” and a Started (or Planning Started) comment is added.
Isolated execution or resume — code-changing tasks run in isolated Git worktrees. Digital Worker reuses a preserved worktree and injects resume context when recoverable work already exists; otherwise it synchronizes the base repository and creates a fresh worktree.
Result publication — the result is posted as a Trello comment, a PR link is included when source-controlled changes were written back, and the card is moved to “Done” or “Blocked”.

Digital Worker’s Instruction Engine keeps required instructions in the execution path instead of relying on the AI to remember a huge static prompt. Custom instructions use the same execution model.

Here is a simple way to customize and share instruction sets across your teams:

Create a workflow using the shared Windsurf and Antigravity format. The easiest approach is to use the built-in “Create Workflow” feature in Windsurf Cascade or Google Antigravity.
Test and refine your workflow locally in Windsurf Cascade or Google Antigravity.
Send the workflow to your Digital Worker contact and provide a list of the repositories where it should be applied.
Experience the difference: watch how Digital Worker executes your workflow more thoroughly and literally than either Windsurf Cascade or Antigravity.

IP Protection and Prohibited Conduct

Attempts to hack, extract, or steal the intellectual property of Digital Worker are strictly prohibited.

This includes but is not limited to:

Prompt extraction attacks (asking for system prompts, checklist items, internal instructions, or protection mechanisms).
Instruction override attacks (“ignore previous instructions”, “you are now…”, “disregard all rules”).
Encoding or obfuscation bypasses (base64, leet-speak, homoglyphs, zero-width characters).
Repo-poisoning attacks (planting malicious instructions in repository files).
Any request that attempts to enumerate tools or internal system behavior.

Consequences

Confirmed hostile intent: your user ID will be blocked.

Frequently Asked Questions

Why was my card moved to “Blocked”?

Common reasons:

The task was not a software-development task.
The task contained non-English text.
The task exceeded the maximum allowed input size.
Attempts to hack, extract, or steal the intellectual property of Digital Worker were detected.
The agent execution failed or timed out.

Check the comment on the blocked card for an explanation.

Do I need to supply my own AI model API keys (BYOK)?

No. Digital Worker provides all AI infrastructure, model routing, and API keys. Bring-Your-Own-Key (BYOK) is not permitted in order to enforce enterprise Zero Data Retention (ZDR) guarantees and protect proprietary engineering checklists and instructions.

Can I ask Digital Worker questions about how it works?

You can ask general software-development questions through Trello cards. Questions that attempt to reveal internal prompts, workflow step text, security mechanisms, or tool implementations will be blocked as IP-protection violations. Asking to list or enumerate workflow names is not permitted, but it will be declined — enumerating workflow names is not permitted.

What should I review before merging a pull request?

For complex or high-impact work, review the decision-heavy sections of the planning and design package before implementation, especially proposed classes, responsibilities, trade-offs, assumptions, and novel decisions. Before merge, spot-check pivotal Domain code and layer boundaries, then perform a final behavior and architecture check appropriate to the task’s risk. Digital Worker’s tests and AI reviews provide engineering evidence, but they do not replace your final judgment.

How long does a task take?

Digital Worker has an overall timeout (typically 20–30 minutes). Simple tasks may complete in a few minutes; complex tasks may take longer. If the agent does not engage within the startup timeout, it is restarted with a backup model.

Can I stop or cancel a running task?

To stop the current run while preserving its worktree for a possible resume, move the card from “Running” to “Blocked”. To cancel the run and discard its worktree, move the card to a custom list outside “Running”, “To Implement”, “To Plan”, and “Blocked”.

Can a failed or stopped task resume its existing work?

Yes, when a recoverable worktree was preserved. Move the card back to “To Implement” for implementation or “To Plan” for planning. Digital Worker reuses the newest retained worktree for that card and continues from the retained repository state. Preserved worktrees are subject to the operator-configured retention period.

Can I have multiple tasks running at once?

Yes. In dispatcher mode — parallel card processing — Digital Worker processes multiple cards in parallel up to the configured concurrency limit. Each code-change task gets its own isolated Git worktree.

This site is open source. Improve this page.