Build your first feature with Cohandry

A guided coding project · Preview 0.1.12

Use Cohandry to add a useful feature to Task Garden, a small task-list app. You will give an agent a bounded assignment, follow its work, try the result, review the changes, and optionally deliver them through GitHub and CI.

Task Garden is the example project you improve, not another application you need to install. The starter already works; your assignment adds high-priority tasks. You do not have to open its page before beginning.

Follow the numbered sections to build your first feature. The field reference at the end explains what to enter in each part of Cohandry.

1. Get ready

1. Open Cohandry 0.1.12 on Windows x64 or Apple Silicon Mac. On Windows, use the single Setup EXE; on Mac, keep the app bundle intact. If macOS blocks this unsigned preview, use the supported distribution instructions; do not disable system protections.
2. Extract the practice kit and copy task-garden-starter into a new folder you own, for example Documents/Cohandry Practice/task-garden. This is the folder your agents will change. Use a disposable copy rather than a real project.
3. Have Node 24+ available for this example. Check node --version and npm --version in Terminal. No npm install is required: the starter has no external packages. Cohandry includes its own launch runtime, but development commands need Node available on your computer.
4. For the GitHub portion, also have Git, GitHub CLI (gh), and a GitHub account. You can skip that portion and work entirely in the copied folder.

Choose your route: for a complete coding-to-GitHub exercise, follow every numbered section. For a first local-only feature, skip section 4 (GitHub preparation) and section 9 (delivery), and choose folder mode in section 5. You can return to GitHub delivery in a fresh practice project when you are ready.

Optional: see the app you will improve. In Terminal, change into your copied starter folder, run npm start, and open http://127.0.0.1:4310. Add a task and try completing it. There is no priority option yet—that is what your agent will add. Stop the server with Ctrl-C. This preview helps you recognize the change; it is not a Cohandry setup requirement.

2. Create your project and give it context

1. Choose Projects → New project.
2. Enter project name Task Garden tutorial.
3. Paste this into Project context:

Task Garden is a small browser-local task list for one person learning Cohandry. Work only in the disposable Task Garden repository. Use vanilla HTML, CSS and JavaScript with Node's built-in tests; add no dependencies, login, telemetry, cloud database or deployment. Preserve task-title escaping and keyboard usability. The current milestone adds high-priority tasks as specified in the imported product brief and acceptance document. Produce measured file evidence and honest test results. Stop at reviewed delivery; publication and merging require my separate explicit action.

4. In Workspace, select Choose later for this first exercise. You can instead attach an existing local clone or choose where to download one. Selecting a folder does not start an execution host.
5. In Resources, upload the starter's docs/PRODUCT-BRIEF.md and docs/ACCEPTANCE.md (or import later under Resources → Import documents).
6. In Team & connection, select Software delivery as the starting team. Inspect the preview: Technical lead, Implementation agent, Code and test reviewer.
7. Keep the project connection Demo.
8. Review the summary. Use Back or the section Edit buttons to correct anything, then create the project.

You may also use Resources → Link repository files to select the two documentation paths from your GitHub repository instead of uploading them. Read access uses GitHub CLI on the coordinator. Linked files show their exact commit and remain snapshots until you choose Check for updates, review the new content, and refresh. Documentation access is separate from code publication.

Expected: the project exists with an amber Paused pill. No model task, GitHub publication or file editing starts just from setup. If setup partly fails, inspect the existing project before retrying; successful stages can remain saved.

Open each main area:

• Work: tasks, Questions, status filters, and Filter this view for agent/workstream.
• Deliverables: received copies of submitted files.
• Team: project agents and execution hosts.
• Resources: imported Sources and Project notes.
• More: Setup, Conversation, Activity history, Automation, Checkpoints and Project settings.
• Project overview and activity: expanded summary, messages and recent handoffs.

Go to Resources → New note. Set key milestone-1-decision and content:

Milestone 1 uses a checkbox for High priority and a text badge on each high-priority task. The High priority filter includes both active and completed high-priority tasks. Existing stored tasks without the new property are normal priority. No sorting, due dates or deployment in this milestone.

Save the note. Under Work → Filter this view → New workstream, create Implementation with scope “Milestone 1 application and tests only. Stop before publication.” You will select it for the coding assignment. Project context explains the lasting purpose; the imported documents specify the feature; this note records one decision. Your assignment later describes the work to do now.

3. Connect and verify a real model

Keep dispatch paused throughout configuration.

1. Open Accounts & API keys. Choose either your supported ChatGPT account connection or a provider API connection.
2. For ChatGPT, complete the app's sign-in and use Test connection. Review the selected account/model. Sign-in and a successful inference test are different checks; record both.
3. For API execution, select the issuing provider (OpenAI, Anthropic, xAI or OpenRouter), enter its key only into the connection field, and Connect. Use an exact model ID supported by that provider. Keys are separate and API requests may be billed.
4. Open Project settings → Connection & billing → Configure. Select the intended route and model for this existing project. Changing global defaults only affects newly created projects.
5. Leave Automatic paid fallback Disabled for the core tutorial. This avoids turning a subscription quota event into an unexpected separately billed exercise.
6. In Team → Configure, inspect each real agent's Connection. Use Inherit project default, unless deliberately testing an override. Pack or existing agents may retain explicit Demo settings; correct those before real work.
7. Use Test connection and inspect the result. Keep the project paused while configuring the host and roles in the next sections. The feature assignment will exercise real model and file access together.

What to expect: a tool-capable model is needed for the file workflow. Enter API keys only in the connection fields; session-only keys may need reentering after restart. Never put credentials into project context, notes or source files.

4. Prepare the GitHub repository and automatic Git path

This optional section prepares GitHub before your agent starts coding. Skip it for the local-only route.

Create a private initialized repository

On the coordinator Mac, authenticate GitHub CLI to your intended account with gh auth login, then inspect gh auth status. The desktop app uses the coordinator's gh access; a GitHub connection in another app is separate. Do not paste authentication tokens into Cohandry notes.

In Terminal, inside your clean copied starter folder:

git init -b main
git add .
git commit -m "Start Task Garden tutorial"
gh repo create task-garden-cohandry-practice --private --source=. --remote=origin --push

The final command creates a real private repository and pushes the starter. Run it only when you intend that action. Pick a unique repository name if it already exists; do not reuse a real project accidentally. If Git asks for your author identity, configure the identity you want attached to this practice repository. If GitHub rejects pushing a workflow, resolve your normal GitHub authorization for workflow files rather than removing CI just to pass setup.

Open the repository on GitHub. Confirm visibility, main, starter files and the Actions run. The included workflow checks npm test and syntax on push-to-main, pull requests and manual dispatch, with a read-only token. No secrets/deployment setup are required. Check your account's Actions availability/usage before running many exercises. This tutorial provides CI, not public deployment.

Connect it to Cohandry

1. Pause the project. Open Project settings → Repository → Connect GitHub / Repository actions.
2. Choose Connect existing repository. Enter its HTTPS URL, such as https://github.com/YOUR-ACCOUNT/task-garden-cohandry-practice.
3. Connect and inspect the returned repository/base branch. Use Check connection for a fresh live access check. Saved metadata is not proof of live authentication.
4. Choose Enable automatic Git workflow and explicitly select the publication permission for this repository. This authorizes submission-branch pushes; PR publication and merging are still separate.
5. Create your section 5 host using the clean repository clone as its absolute folder and Allow isolated Git task workspaces and push submission branches. The worker computer needs its own functioning Git push authentication. On the local Mac that is usually the same OS account; still verify it rather than assuming.
6. The clone must match the connected remote. Keep it clean. Do not run another agent/editor that changes the same checkout during setup.

New measured-file tasks on this host fetch the configured base and use isolated task worktrees/branches. The worker commits submitted files and pushes its submission branch. Inspect the recorded base, branch, commit, digest and diff. Ordinary planning/reviewer tasks remain text work.

Expected: the section 6 feature task has a recorded Git submission. Approval is not integration, and a pushed branch is not a PR. Dirty/unsubmitted files, auth errors or conflicting base changes should stop for inspection, not trigger a force-push.

5. Configure a local development host and roles

Before real code work, prepare GitHub using section 4 if you want automatic Git delivery from the first feature task. Otherwise use folder mode for this exercise. Read both choices before creating the host: the current managed host form does not offer a general edit-every-setting screen.

In Team → Add this computer, enter:

Read the permission description before saving. This grants real host-account execution, not an OS sandbox. The host should become Online. If offline, Start it and Refresh. The path is on the computer running the coordinator, not an arbitrary other machine.

Configure the three pack roles without replacing their useful existing settings:

Implementation agent

• Responsibilities: “Implement bounded Task Garden changes, add meaningful tests, run relevant checks with approval, and submit measured changed files plus a concise report.”
• Additional guidance: “Preserve existing behavior and title escaping. Do not install packages, deploy, edit credentials, merge, or publish a PR. Report failed checks and untested behavior honestly.”
• Execution host: Task Garden Mac. Clear irrelevant required capabilities; ensure selected ones are actually available.
• Require measured files. Default approval: Required reviewer(s), then you.

Code and test reviewer

• Responsibilities: “Inspect submitted source and test evidence against the product brief and acceptance criteria. Identify concrete defects; approve or request changes against the exact submission.”
• Coordinator execution, real inherited model, Can coordinate work Yes.
• May review work from: Implementation agent.
• May assign work to: Implementation agent, if you want bounded correction assignments.

Technical lead

• Responsibilities: “Break approved milestones into bounded assignments for the implementation agent, inspect progress and evidence, coordinate the authorized reviewer, and stop at owner decisions.”
• Coordinator execution, real inherited model, Can coordinate work Yes.
• May assign work to: Implementation agent (and reviewer if needed by the intended plan).
• Grant review targets only if you actually want the lead to act as a reviewer. Do not make every agent a competing reviewer.

Save the reviewer first, then reopen the implementation agent and select that reviewer under Required reviewers of this agent's submissions. This option only lists agents already authorized to review it. Keep Role label and Additional guidance optional; blank Role label uses the name.

Run More → Setup or Project settings → Check setup and resolve blockers before queueing the feature task.

6. Implement the priority feature with a direct task

If using automatic Git delivery, complete section 4 before queueing this task. Policy applies to new measured-file tasks, not retroactively to old ones.

Choose New work → Direct task, assigned to Implementation agent, workstream Implementation:

Task name: Add high-priority tasks

What should this agent do?

Read docs/PRODUCT-BRIEF.md and docs/ACCEPTANCE.md, then implement milestone 1. Add a labeled High priority checkbox when adding a task, a visible text badge on high-priority tasks, and a High priority filter. Preserve add/complete/delete, current completion filters and reload persistence. Existing tasks without highPriority must be treated as normal. Add focused tests and update README. Use existing vanilla JavaScript and Node tools; install nothing. Request approval for npm test and npm run check, or their equivalent Node invocations. Publish measured evidence for every changed source, test and documentation file after the final changes and checks. Stop at submission. Do not publish a PR, merge or deploy.

Success criteria:

All nine criteria in docs/ACCEPTANCE.md are met. Original tests remain passing; added tests verify priority and compatibility. Provide changed files, actual commands and results, and honest browser-test limitations. The priority badge uses text, controls are labeled, and task titles remain rendered as text. Submit measured files for review.

Set Required reviewer(s), then you and Require measured files. Queue while paused, inspect instructions, then Start new work.

Approve commands and follow activity

Open Inspect task. Watch Activity, Console and Checks. For every requested command, inspect executable, arguments, working directory, purpose and timeout. Approve once only if it matches the exercise. npm test may be represented as Node plus the npm CLI script rather than a bare npm executable. Deny unrelated commands.

Approve the expected tests/checks promptly; approval expires after about five minutes and waiting consumes runtime. Watch streamed output and final exit status. Failed checks should return to the agent for correction, not be described as a pass. Later edits can make earlier checks stale. A successful exit is evidence for that command, not proof of every acceptance criterion.

Expected: real edits exist, relevant tests run, received files appear, and the source task awaits its configured review/owner gate. If only prose is returned, the wrong executor/connection or missing evidence configuration is a failure to investigate.

7. Try your app in the owner shell

Choose a non-running task associated with your trusted managed host. Pause new dispatch and let active editing finish before you touch the same files.

1. Open Inspect task → Owner shell → Start shell. Read the shown path and shell.
2. Run pwd to confirm the folder. If you chose GitHub, also run git status --short --branch. In automatic Git mode, the directory must be that task's existing worktree, not the main clone. A queued task whose worktree has not been created cannot open one yet.
3. Run npm test and npm run check. These are your own shell commands; they do not approve pending agent commands.
4. Run npm start, open http://127.0.0.1:4310, and do section 8's browser checks. If another practice server is already running, stop it first; otherwise you may inspect the wrong checkout. Stop the server with Ctrl-C.
5. Use this shell when you want to run your own checks or inspect the app alongside the agent. You can also open the task workspace in an installed editor.
6. Choose Stop. Close/reopen the task and verify you do not have a persistent server running in that shell.

Shell start/exit makes prior task checks potentially stale. After owner edits, rerun checks and have the worker remeasure/resubmit evidence before approval. Do not edit an already approved Git submission and assume its approval now covers those changes.

The shell starts in the workspace but has your account's broader privileges. Terminal text is not sent to the model and is not kept as coordinator command logs. Keep relevant results in an appropriate project note. The shell is local-only, not a remote terminal/takeover of agent stdin; closing the task or quitting ends it. It is not a persistent development-server manager.

8. Inspect deliverables and request a real correction

1. In Deliverables, inspect each submitted copy. Open text previews, inspect size/SHA-256/revision and download a file. Compare at least one copy with the submission report. Images can be previewed when provided; binary metadata alone does not mean a reviewer saw its contents.
2. Inspect the automatic reviewer assignment. It should refer to the original task and current evidence. A completed reviewer task is not enough: look for an actual approval or request-changes decision on the source revision.
3. Use Workspace actions → View changes. This is a live local Git diff; it does not approve work. Open task workspace reveals the correct workspace; optional VS Code/Cursor buttons require those editors installed.
4. Run Task Garden from the actual task workspace (section 7) and perform every acceptance check. Create normal/high-priority tasks, complete a high-priority one, verify the priority filter includes it, reload, delete, and use the keyboard. Enter <img src=x onerror=alert(1)> as a title: it must display as text, without executing.
5. Check the compatibility tests in the submitted evidence: tasks saved without a priority property should still work as normal-priority tasks.
6. Request one purposeful improvement, even if there is no defect: “Add a concise README section explaining how the High priority filter interacts with completed tasks. Keep behavior unchanged; rerun checks and resubmit measured evidence.” Record why the first submission was not accepted.
7. If a configured reviewer/lead creates a correction, follow that existing task. Otherwise explicitly ask the Technical lead for this bounded correction. Do not repeatedly create duplicate fixes. Automatic-Git corrections must start from the rejected submission's recorded commit; use the supported correction flow where available rather than a new unrelated branch from main.
8. Inspect the replacement submission, fresh evidence, reviewer decision and your final owner gate. Approve only the intended current revision. Keep the rejected history visible.

Expected: requested changes remain in history, corrected work has new evidence, and stale approval cannot silently apply to changed bytes. A final human approval may be unavailable until required reviewers approve. Reviewer-only tasks intentionally do not offer owner approval; cancellation is different from approval.

9. Publish, check, correct and merge the approved submission

Publish a draft PR

After exact-revision review and owner approval:

1. Open the task's Review repository delivery, or Repository actions.
2. Choose Publish approved worker submission and select the intended task. Authorize that operation for this repository/task.
3. Open the resulting draft PR. Verify head branch/commit, base main, files and description. Confirm it contains only the intended change.
4. The draft may need to be marked Ready for review in GitHub before merge. Cohandry does not automatically do that for you.
5. Choose Check PR, reviews and CI in Cohandry. Compare with GitHub's Checks/Files changed/Conversation pages. A successful Actions run should correspond to the submitted head, not an older commit.

Do not create a second PR if a response was lost; inspect GitHub first. Repository operations can have external effects even if a response fails.

Exercise PR feedback

Add a small actionable comment in your practice PR, for example: “Please clarify in README that tasks are stored only in this browser and are not synchronized.” Then refresh delivery in Cohandry.

Choose Create correction from PR feedback, inspect the feedback and authorize the bounded correction. The resulting assignment must pass the same measured-file and reviewer/owner gates. PR comments are input, not permissions. Inspect the corrected submission and its delivery. The old PR may remain for history; identify the replacement PR/head explicitly. Do not assume stacked PR rewriting or automatic closure.

Merge and verify integration

1. Check the current PR is ready, conflict-free, approved according to your repository policies, with at least one successful CI/check source and no pending/failing checks or outstanding review requests.
2. Choose Merge approved pull request only when you intend to change main. Review the selected task/revision/commit and explicitly authorize it. Cohandry requests an exact-head squash merge; GitHub policy may still block it.
3. Choose Verify merged submission / release dependents (or refresh the delivery until verification is recorded). Confirm the actual merge commit is present in the fetched base.
4. Inspect GitHub main and its post-merge CI. Fetch/pull the practice clone only when no task/editor is using it. Run tests from the integrated main and manually verify the app again.

Approval → PR publication → merge → verified integration are distinct steps. The active coordinator periodically monitors some published submissions, but does not automatically merge or invent a repair assignment. Paused projects are excluded from this monitor; use explicit refresh/verification while paused.

Test a dependent task

Ask the lead to create one documentation assignment depending on the feature task: “After the priority feature is integrated, add a short milestone summary to README. Do not modify runtime behavior. Stop at reviewed submission.” In automatic Git mode, it should remain blocked until the prerequisite's integrated commit is verified, even if the predecessor was approved. Confirm the dependency explanation and later release. If no structured child assignment was created, prose saying “I assigned it” is not a pass.

A replacement correction can release dependencies after verified integration without erasing the original rejection. Cross-repository promotion and stacked PR management are outside this exercise/support boundary.

10. Finish and keep learning

You have given an agent a development assignment, inspected commands and evidence, tried the app, requested a correction, and approved a reviewed result. If you chose GitHub, you also published a PR, checked CI, and verified integration.

Pause the practice project, stop any development server and shell, and keep the project for another session. You can return to this practice project to explore another feature, or start a new project with your own idea.

Field reference

Use each field for one purpose. Examples in Cohandry are hints, not saved instructions. Replace them with your actual input.

Project context is snapshotted into new assignments. Editing it later does not rewrite old tasks. Imported sources are references; current decisions should identify the controlling source and revision. Agent settings also do not rewrite an already active attempt.