Working with AI Agent Assistants

AI coding agents — specifically Claude Code — are used at Arda to accelerate implementation of well-scoped work. This guide covers how to collaborate effectively with agents, how multi-agent teams are structured, how to stay informed during a run, and what patterns to avoid.

1. General Principles for Effective Collaboration

Give Agents Concrete, Bounded Tasks

Agents perform best on tasks with:

A clearly defined goal and acceptance criteria.
A bounded scope (specific files, directories, or components).
Explicit constraints (what to change and, equally important, what not to touch).

Vague requests produce vague results. “Improve the operations service” is a poor prompt. “Add a GET /items/{id} endpoint to the operations service, following the existing controller pattern in ItemsController.kt, with a corresponding Bruno workflow test” is a good one.

Provide Upfront Context

Agents do not have memory across sessions. If relevant context is not in the codebase or the prompt, it will not be used. Before starting a significant task, consider:

Pointing the agent to related files, patterns, or prior decisions.
Referencing the relevant decision log (DQ-NNN) if a design choice constrains the approach.
Stating explicitly which patterns to follow (e.g., “use the factory pattern as in createArdaEntityDataGrid”).

Review Output Critically

Agents can produce plausible-looking but incorrect code. Review agent output with the same rigour as you would a junior engineer’s PR:

Run the tests.
Read the diff.
Check that the agent did not silently ignore a constraint or scope boundary.

Agents will sometimes solve a problem correctly but via a suboptimal path. It is reasonable to ask for a revision with specific feedback.

Keep Sessions Focused

Mixing many unrelated tasks in one session degrades quality. If you need changes across several unrelated areas, split them into separate sessions or separate agents on a team.

2. Multi-Agent Teams

When to Use a Team

A multi-agent team is appropriate when:

A project has multiple independent sub-tasks that can proceed in parallel.
The total work exceeds what a single session can hold in context without degradation.
Tasks can be cleanly assigned to different working directories or repositories.

For small, focused changes (a few files, one component), a single agent session is faster and produces fewer coordination artifacts.

How Teams Are Structured

A team consists of:

A team lead (coordinator) that reads the task plan, spawns specialist agents, tracks progress, and reports back.
Specialist agents assigned to individual tasks (e.g., a back-end engineer agent, a QA agent, a documentation agent).
Optionally a continuous improvement observer that monitors the session and produces a post-project improvement proposal.

All of this is driven by a task-plan.md file in a project directory. The plan contains the task list, dependency graph, parallelization strategy, persona assignments, working directories, and worktree strategy.

The task-plan.md File

The task plan is the contract between you and the team. The team lead will follow it precisely. A well-formed plan includes:

Section	What it contains
Task list	All tasks with IDs, dependencies, assigned persona, and acceptance criteria
Parallelization strategy	Which tasks run concurrently, which are sequential
Personas table	Agent type, name pattern, and working directory for each role
Scope boundaries	Explicit in-scope and out-of-scope items
Worktree strategy	Branch names, worktree paths, integration branch name (if applicable)
Handoff/exit gate	Steps to verify completion before handing back to the engineer

Project plan templates and examples live in the Arda workspace repository under workspace/projects/.

Launching a Team

Once you have a task-plan.md, ask Claude Code to launch the team:

Launch the team for workspace/projects/<path-to-plan-directory>

Before spawning agents, the team lead will:

Validate all working directories exist.
Check whether a worktree strategy is needed (see below).
Ask clarifying questions about any ambiguity in the plan.

If everything looks good, it will spawn the team and begin execution autonomously.

Worktree Strategy

When two or more agents write to the same repository in parallel, they must work in separate git worktrees to avoid conflicts. The conventions are:

Worktrees are grouped under a parent directory at the workspace root: ${projectName}-worktrees/${taskName} (e.g., inventory-worktrees/registry).
Branch names follow: ${githubUsername}/${projectName}/${taskName} (e.g., jmpicnic/inventory/registry).
All agents in worktrees must use absolute paths for every file operation — relative paths resolve against the wrong directory.
When all tasks in a worktree are done, its branch is merged into the integration branch (not directly into main).
One PR is opened from the integration branch to the base branch, giving reviewers a single unified diff.

If a plan has two or more parallel agents writing to the same repository but no Worktree Strategy section, the team lead will flag this before starting and ask for clarification.

Permission Configuration

Agents run with bypassPermissions mode so they can operate without prompting for every file edit. For worktree directories, the project-level settings at /Users/jmp/code/arda/.claude/settings.json must explicitly allow the worktree paths — glob patterns like *-worktrees/** do not match hyphenated directory names reliably. Spell out each worktree parent explicitly:

"allowedPaths": [
  "inventory-worktrees/**",
  "fe-coverage-worktrees/**"
]

If agents appear stuck and are producing no output, the most common cause is a missing permission entry. Check the coordinator’s terminal pane for silent approval prompts.

3. Communication During a Run

Slack Notifications

When you want to be notified of team progress without watching the terminal, ask for Slack notifications when launching:

Launch the team for workspace/projects/<path> with Slack notifications

This spawns a user-comms agent that posts to your configured Slack channel. Messages follow a standard format:

Type	What you will see
Project start	Team started, agent count, task count
Task complete	Which task finished and who completed it
Question	A blocker that needs your input before the team can continue
Heartbeat	Periodic alive signal after each task boundary
Project complete	Final summary with artifacts produced

To receive Slack notifications, the following credential files must exist:

~/.config/arda/secrets/slack-bot-token
~/.config/arda/secrets/slack-channel-id
~/.config/arda/secrets/slack-bot-user-id

See the setup instructions in the workspace repository under workspace/instructions/claude/scripts/slack-setup.md.

Answering Questions

When the team posts a question to Slack (prefixed with QUESTION:), reply in the same thread. The user-comms agent polls the thread and delivers your answer to the blocked team lead, which then unblocks the relevant agent.

Keep answers specific. If the question is about which pattern to follow, point to a file. If it is about scope, confirm explicitly what is in or out.

4. Monitoring Team Progress

Checking Team Status

At any point while a team is running, ask:

How's the team doing?

or for a specific team:

/team-status <team-name>

This runs the team status script and produces a report covering:

Members: name, agent type, active/inactive status, working directory.
Tasks: status (done / in-progress / pending), owner, blockers, and a progress bar.
Worktree state: git branch, uncommitted changes, HEAD commit for each worktree.

Understanding Task States

Status	Meaning
`pending`	Not yet started; dependencies not met
`wip`	Assigned to an agent and in progress
`completed`	Done and verified against acceptance criteria
`blocked`	Waiting on a dependency or a user answer

The TaskList is the single source of truth for progress. The team lead updates it immediately when each task completes, and runs a consistency check at each phase gate.

Identifying Stale Worktrees

The status report will flag worktrees whose branches have already been merged but whose directories have not been cleaned up. These are safe to remove:

git worktree list
git worktree remove <workspace-root>/${projectName}-worktrees/${taskName}
rmdir <workspace-root>/${projectName}-worktrees   # if now empty
git worktree prune

Only remove a worktree after confirming there are no uncommitted changes (git -C <worktree-path> status).

5. Project Byproducts

When a team completes its work, it writes a set of byproduct files to <project-directory>/byproducts/:

File	Contents
`changelog.md`	Summary of changes made during the project
`learnings.md`	New knowledge about the codebase or technologies useful for future tasks
`suggestions.md`	Improvement suggestions, identified risks, technical debt, documentation gaps

A continuous improvement proposal is also written to <project-directory>/continuous-improvement-proposal.md. Review these files — they often contain useful observations that would otherwise be lost.

6. Best Practices and Anti-Patterns

Best Practices

Write a complete task plan before launching. The more precise the plan, the less the team needs to stop and ask questions.
Define acceptance criteria per task. Agents use these to self-verify. Without them, tasks are marked done when the agent runs out of obvious work, not when the work is actually correct.
Use the worktree strategy for parallel writes. Even if it feels like more setup, merge conflicts mid-run are more disruptive.
Name agents with the persona prefix and task. For example fe-nextjs-upgrade or qr-phase1-review. This makes it easy to identify who is doing what in the status report.
Redirect stdout/stderr to scratch/. Long-running commands (builds, test runs) should write to <project-dir>/scratch/, not the repo root, to keep the workspace clean.
Run pre-push checks before pushing. Agents do not run linting, type-checking, and tests before pushing unless explicitly instructed. Before any push to origin, verify npm run lint, npx tsc --noEmit, and npm run test pass locally.

Anti-Patterns

Do not give agents access to the entire workspace without scope boundaries. Without explicit working directory restrictions, agents may make changes in unrelated repositories.
Do not skip the worktree strategy when two agents write to the same repo. This reliably produces merge conflicts or lost work.
Do not assume the agent read your prior conversation. Each session starts fresh. Put the context in the prompt or in the plan.
Do not treat agent output as a substitute for review. Agents make mistakes. The engineer is accountable for what gets merged.
Do not bundle unrelated tasks into one agent session. Context window limits cause quality to degrade as sessions grow longer.
Do not launch a team without naming the coordinator. Use coord-<project-name> as the coordinator name. Generic or auto-generated names make it impossible to identify the right team in the status report.

working-with-agents.md (this page)
release-lifecycle.md — Integration branch and worktree cleanup conventions used by agent teams.
Arda workspace repository — Agent persona definitions, skill library, project plan templates, and the launch-team and team-status skill documentation.