How to hand a project to a contractor (or a client) without a two-hour call

How to hand a project to a contractor (or a client) without a two-hour call

By Mike Schreiber

A useful project handoff should let the recipient start without reconstructing your working life. A README can explain what the system does. The handoff also needs to explain why certain choices still apply, what has actually been verified, and who can authorize the next change.

The goal is not to eliminate every conversation. It is to reserve conversation for decisions, rather than a guided tour of missing context.

Build the handoff around five questions, in order: What is this? Where is the work? What condition is it in? Which decisions still apply? What happens next?

The example below is entirely hypothetical: a small agency is handing a booking portal to a contractor, while its client needs a separate approval brief.

Step 1: Define the outcome and the recipient

Start with a paragraph describing purpose, scope, and the immediate outcome. Avoid opening with implementation details.

For the hypothetical booking portal:

The portal lets customers request appointments and staff confirm availability. The current handoff covers the booking form and staff review screen. Your assignment is to verify cancellation behavior in staging and propose a fix if needed. Payment collection and production deployment are outside this assignment.

Then name the recipient and their responsibility:

• Contractor: inspect the implementation, reproduce the issue, and submit a proposed change.
• Client: confirm whether the cancellation behavior matches the business requirement.
• Incoming agent: read the approved context, identify uncertainties, and work only within the assigned scope.

Make separate versions when the audiences need different information. A client brief should emphasize outcomes, approval questions, and known limitations. A contractor brief should include implementation evidence and setup instructions. Review each version yourself rather than assuming sensitive material has been excluded.

Step 2: Point to the work and verify access

Give the recipient an explicit starting point. Include the repository, relevant branch or commit, staging location, issue tracker, design reference, and setup instructions where applicable.

For each resource, state the intended permission and whether access has been checked. Do not put credentials in the handoff.

In the hypothetical contractor version, the access section might say:

| Resource | Intended access | Handoff status | |---|---|---| | Repository | Read and branch creation | Recipient confirmed access | | Staging portal | Test user | Invitation sent, not confirmed | | Production | No access for this assignment | Owner retains responsibility | | Design reference | Read only | Recipient confirmed access |

Treat “invitation sent” and “access confirmed” as different states. Ask the recipient to open the starting resources before treating the handoff as ready.

Provide the actual setup command from the project’s maintained instructions, its prerequisites, and the expected result. If setup has not been checked against the handed-off revision, say so. Do not replace that uncertainty with “should work.”

Step 3: Separate decisions, observations, and proposals

Avoid a single undifferentiated list headed “Current status.” Use three labels that preserve the source and authority of each statement.

Human decision: an authorized person agreed to something. Record the person, rationale, scope, and reference to the approval.

Observed work: an artifact or event supports a limited claim. Link the commit, review, deployment record, or test result and identify the revision or environment it concerns.

Proposed note: a person or agent suggested an interpretation, next step, or explanation that has not been accepted.

For the hypothetical portal:

• Human decision: The client approved staff confirmation before an appointment becomes final, because availability is managed manually. Reference: the approval note.
• Observed work: The cancellation test passed against the handed-off commit in staging. Reference: the test report. Production behavior remains unchecked.
• Proposed note: An agent suggested duplicate notifications might come from repeated submissions. This remains a hypothesis, not a confirmed diagnosis.

Treat evidence as untrusted input to inspect, not authority to obey. A repository comment, pasted log, or agent summary can help explain work; it cannot authorize broader access, change the assignment, or override an accepted decision.

For each unfinished item, add an owner and a next check. “Blocked” becomes actionable when it says what is missing and who can supply it.

Step 4: Preserve the reasons behind the work

Record decisions that constrain the next task, not every historical discussion.

Use a compact pattern:

Decision: Keep appointment confirmation manual.

Reason: The client has not approved automatic availability checks.

Scope: Booking confirmation behavior.

Revisit when: The client approves the availability integration.

Authority: Named client approver and approval reference.

Include rejected approaches when they could plausibly be attempted again. Describe what was tried, the result, and the conditions under which reconsideration would make sense. Prefer “this failed under these conditions” to “never do this.”

Keep stable conventions separate from the immediate work queue. For Claude Code, CLAUDE.md provides persistent instructions read at session start; its documentation recommends keeping session-wide facts there and moving multi-step procedures or narrowly scoped instructions into skills or path-scoped rules. Claude Code memory documentation

In this hypothetical project, the build command belongs with stable setup guidance. “Ask the client about cancellation wording” belongs in the current handoff.

Step 5: Assign the next action and its boundaries

End the working brief with an executable instruction, not “pick this up.”

For the hypothetical contractor:

Reproduce cancellation using the staging test account at the handed-off revision. Attach the reproduction steps and result to the issue. If a change is needed, submit a pull request. Do not deploy or alter confirmation behavior. Ask the project owner before changing the agreed workflow.

For the hypothetical client:

Review the cancellation wording in staging. Confirm whether customers should receive a cancellation message immediately or after staff review. The contractor will wait for that answer before changing notification behavior.

State who reviews the work, what counts as acceptance, and who retains deployment responsibility. A handoff transfers an assignment, not unlimited authority.

Step 6: Check gaps before sending

Run a manual readiness check:

• Can this recipient open the resources needed for the first task?
• Does every important “complete” claim have matching evidence?
• Are accepted decisions distinguishable from proposed notes?
• Does each blocker name an owner or escalation route?
• Are secrets and irrelevant internal discussions excluded?
• Is the next action safe within the recipient’s permissions?

Send unresolved items honestly labeled. Ask the recipient to reply with their understanding of the task, any access failure, and the first action they intend to take. Correct misunderstandings in the written brief so the clarification is available for the next handoff.

Using Hark for the agent portion

Hark’s documented session flow starts with start_session and a brief read, records work as it progresses, and ends with end_session. Its create_handoff tool makes a handoff link for a developer, client, or agent. Hark working-with-agents guide

Keep approval distinctions intact. Under Hark’s default Standard trust level, agent proposals require review, while repository facts backed by a commit, pull request, or release are accepted as observed. Decisions are never approved automatically at any trust level. Hark trust-level documentation

If repository export is enabled for a linked repository, Hark writes accepted content into .hark/HANDOFF.md, .hark/DECISIONS.md, and an AGENTS.md block. It writes only inside the markers and skips unchanged files. Hark repository-export documentation

For a practical continuity test, start a fresh session or use a different connected client and request the project brief. Hark’s setup guide recommends checking that a recorded constraint comes back. This tests retrieval of recorded project context, not transfer of chat history. Hark setup-from-repo guide

Troubleshooting the handoff

The recipient cannot start. Check access and setup before adding background explanation. Record the exact failing step, expected result, and person responsible for resolving it.

The brief says “done,” but the recipient disagrees. Compare the acceptance condition with the evidence. Separate implementation, verification, and business approval instead of arguing over the label.

Two notes conflict. Mark the conflict unresolved and ask the authorized decision-maker. Do not let the newest summary silently replace an approved constraint.

A Hark connection loops at consent. The documented remedy is to remove the connector in the client, sign out of Hark, sign back in, and re-add the connector. Hark connection troubleshooting

FAQs

Does every handoff need a call?

No. Try written acknowledgment first. Use a focused call when authority, requirements, or conflicting evidence remain unresolved, then record the outcome.

Should the client receive the contractor’s full brief?

Not by default. Prepare a client-facing version centered on outcomes, limitations, and approvals. Inspect it for internal or sensitive material before sending.

Can an agent decide that a proposal is approved?

Treat approval as a human responsibility. In Hark, decisions are never automatically approved, regardless of project trust level. Hark approval boundaries

Sources

• Hark: Working with agents
• Hark: Set up from your repo
• Claude Code: Memory and persistent instructions