> ## Documentation Index > Fetch the complete documentation index at: https://docs.droyd.ai/llms.txt > Use this file to discover all available pages before exploring further. # Initialize Task > Create a task folder, replace the scaffold with a real challenge, write the verifier, and make a first debug run. By the end of this page you will have a task that validates, is saved as a private revision, and has been attempted once by a model so you can see whether it works. You need a signed-in CLI (0.1.29 or newer) and, for the debug run, an [OpenRouter](/setup/openrouter) key. The example throughout the task guides is `expense-audit`: a task that gives the agent a folder of expense claims and a reimbursement policy and asks it to list the claims that break the policy. ## 1. Decide the outcome and the check Write two sentences before touching the CLI: what the agent must produce, and how a verifier will decide it is right without trusting the agent. For `expense-audit`, the agent writes `flagged.json` naming each non-compliant claim and the rule it broke, and the verifier compares that file with a private answer key. If you cannot state the check, the task is not ready. A task whose only evidence is the agent saying it is done cannot be scored. ## 2. Choose a starter and initialize | Starter | Use it for | | -------------------- | ------------------------------------------------------------------------------------ | | `terminal` (default) | Files and tools in `workspace/`, scored from the agent's actions and outputs | | `repo-python` | A Python repository at `repo/`, scored by hidden tests run after the agent's changes | | `repo-node` | A Node.js repository at `repo/`, scored from the agent's actions | ```bash theme={null} droyd task init expense-audit --starter terminal --json cd expense-audit ``` Init writes the required structure with explicitly unfinished placeholders: * `README.md` is the task description the agent reads and the judge's input. * `workspace/INSTRUCTIONS.md` and the rest of `workspace/` hold what the agent may read. * `droyd_env.json` declares the runtime, budgets and a one-line theme statement. * `expense_audit/taskset.py` and `toolset.py` define the task rows, the agent's tools and the reward. * `expense_audit/data/expected.json` is where the private answer key goes. * `seeds/world.json` is the registry of people and organizations; it starts empty. * `AUTHORING.md` is local guidance and is never uploaded. To study a complete worked example instead, run `droyd task init ledger-example --example ledger-forensics` in a separate folder. Examples are reference material; do not copy their answers into your task. ## 3. Replace the scaffold Write the real task description in `README.md` and the operating instructions in `workspace/INSTRUCTIONS.md`. Put the expense claims and the policy document under `workspace/`. Fill in the theme statement in `droyd_env.json`. Every `TODO` must go; a placeholder that raises or returns zero reward is not a finished task. Install the Droyd skill in the task folder so your coding agent can help with the rest: ```bash theme={null} droyd skill add droyd --codex --json ``` ## 4. Author the verifier The verifier lives in your task package and never ships to the agent. Keep the answer key in `expense_audit/data/expected.json`, load it in the reward function, and compare it with what the agent produced. For repository tasks, put independent checks in `hidden_tests/`; they run against a fresh checkout with the agent's changes applied, so the agent's own test output is never the score. Remove the placeholder exceptions and unconditional failures as you complete each part. Review the agent-visible files for anything that leaks the answer, such as a filename or a comment. ## 5. Validate and save a revision ```bash theme={null} droyd task validate --json droyd task push -m "First complete draft" --json ``` Validation checks layout, file roles, sizes and the manifest. It does not run anything. Push saves an immutable private revision and returns the task id; it starts no compute and is not a submission. **If validation fails**, the response names the check and the file. Placeholder content, a missing role, an oversized file, or a dependency declared without a lock file are the usual causes. Fix and rerun. ## 6. Make a first debug run ```bash theme={null} droyd task run --model -n 2 --json droyd task runs --json droyd task trajectory ``` A debug run attempts your pushed revision with a model from Droyd's catalog and records a trajectory for each rollout. Read the trajectories before you read the scores: a run that solved the task by finding the answer in a README, or that failed because an instruction was ambiguous, tells you what to change next. Debug runs are billed as runtime plus your OpenRouter usage, and they are never official measurements. **Success:** you have a validated task, a saved revision, and at least one trajectory you have read. Aim for a task that a strong model solves sometimes but not always. ## Next steps * [Adding World Data](/tasks/world-data) adds a repository or simulated services. * [Submitting Tasks](/tasks/submitting) explains admission and what acceptance means. * The [CLI command reference](/cli/command-reference) lists every namespace; run `droyd task --help` for the options of your installed version. **In active development** Task authoring is in active development. This page describes how it is planned to work; details may change slightly. `droyd task init ` accepts `--starter terminal|repo-python|repo-node` or, exclusively, `--example ledger-forensics|quarterly-rollup-python|quarterly-rollup-node`. New Python starters declare `python_environment: "shared-root-v1"`; declare solver packages in root `pyproject.toml` and verifier-only packages under `[dependency-groups].verifier`, then run `droyd task lock`. `task push [-m ]` persists an immutable revision without compute. `task run` requires `--model` and accepts `-n 1|2|4|8|16` and `--max-tokens-per-response`. Gold traces are optional; never fabricate a passing trace or weaken the verifier to make one pass. Use `task status --json` to read gate results; `task submit` is a separate action.