The Map Is Not the Territory - Dep-Aware Agent Between Explorer and Builder
The intelligence problem
A reconnaissance team maps the territory on Monday. They produce a thorough report: entry points, structural layout, active systems, the works. It's accurate. They did their job well.
On Thursday, the strike team goes in with that report.
What nobody checked: on Tuesday, they rotated the guard shift. On Wednesday, someone welded the east door shut. The report is still 90% correct. The 10% is where things go wrong.
This is the operational gap that every intelligence agency, surgical team, and eventually every engineering org confronts: the distance between when analysis runs and when implementation starts is not zero. Things change in that gap. Nobody announces it. It doesn't feel like a change that matters.
Until it does.
Your Explorer's map goes stale
The standard harness workflow - Lead → Explorer → Builder → Reviewer - solves the right set of problems. Explorer maps the codebase so Builder doesn't go in blind. Builder implements against a real picture of the project, not a guess. Reviewer verifies before anything closes.
But Explorer produces a snapshot. It's accurate at the time it ran. The codebase it analyzed and the codebase Builder starts writing against are only guaranteed to be the same if nothing changed between the two sessions.
In practice, something almost always changes. A dependency gets bumped. A config shifts. Someone runs npm install before the next session starts. Nobody announces it. Doesn't feel significant.
Then drizzle-orm goes from 0.36 to 0.45 - a major bump - and Builder implements using query patterns that changed in the release. The Explorer's analysis was correct. The plan was solid. The code almost works. Nobody lied. Nobody missed a step. The workflow ran cleanly. The ground just shifted between phases and nobody checked.
That's the failure mode v1.6.4 is built to close.
Website: https://stack.cardor.dev/ahk
A fifth role for a specific problem
The standard harness workflow has four roles: Lead (orchestrates), Explorer (reads and maps), Builder (implements), Reviewer (validates). Each has a defined permission scope. Each has a clear position in the chain.
The Consultant is a fifth role, but it's not part of the standard chain - it's conditional. Lead invokes it only when the situation warrants it:
When deps.check returns significant: true
When the task explicitly touches package.json, dependencies, or config files
When .harness/deps-lock.json doesn't exist yet (first task, no baseline)
For routine feature work with stable dependencies, the Consultant never enters the picture. The chain stays at four roles. The Consultant adds overhead only when that overhead is justified.
The MCP tools that make it work
Two new tools ship with v1.6.4, and both are exclusive to the Consultant role - no other agent can call them.
deps.snapshot
Captures the current state of package.json (both dependencies and devDependencies) and writes it to .harness/deps-lock.json with a timestamp. This is the baseline. It runs automatically the first time the Consultant is invoked on a fresh project.
{
"capturedAt": "2026-06-05T10:23:00.000Z",
"message": "Snapshot saved to .harness/deps-lock.json"
}
deps.check
Diffs the current package.json against the stored baseline. Returns a structured result:
{
"significant": true,
"added": ["zod@3.24.0"],
"removed": [],
"majorBumps": [
{ "name": "drizzle-orm", "from": "0.36.0", "to": "0.45.0" }
],
"advisory": "Run npx autoskills to refresh agent skill files after dependency changes.",
"snapshotDate": "2026-05-15T08:00:00.000Z"
}
significant: true means something changed that warrants a full Consultant pass. Minor patches and no-change cases return significant: false, and the Lead can skip the Consultant entirely.
What the Consultant actually produces
The Consultant's output is not a list of packages. It's structured advisory that the Builder reads before writing a single line of code.
Using actions.write, the Consultant records four sections to the task's action history:
Patterns to follow - existing conventions in the codebase the Builder must respect. Not general advice. Specific to what Explorer found.
Risks & warnings - what could go wrong given the current change set. A major ORM bump means query patterns may have changed. A new validation library means the existing pattern for form handling is now inconsistent. These aren't hypotheticals - they're derived from the actual diff.
Best practices - key considerations for this task given the project's current state.
Dependency notes - only when the task touches package.json. What changed, what the breaking changes are, and whether agent skill files need to be refreshed.
The Builder reads all of this via actions.get(taskId) before starting. Explorer's analysis plus Consultant's advisory gives Builder the full picture - not just what the codebase looks like, but what changed and what to watch for.
The advisory-only constraint is not an accident
The Consultant has Read and Bash access (for reading files and running safe diagnostic commands). It does not have write access. Cannot create files. Cannot modify source. Cannot touch the database.
This is intentional, and it matters.
An advisory role that can also write is a role that will, at some point, decide the advisory isn't enough and start making "small fixes" on the way to handing off. That's how you end up with an agent that's half-consultant, half-builder, and fully unclear about what it changed. The Consultant's value is precisely that it stays read-only: it can be thorough, it can be wrong, and it can be ignored - and none of those outcomes damage the codebase.
The mandatory docs criterion
The same release ships a second change that's smaller in implementation but meaningful in practice: every task now gets a mandatory acceptance criterion appended by the Lead before any work begins.
The criterion reads:
"Docs/README analysis: [describe whether docs/, README.md, or other documentation files need to reflect this change and what specifically - or explicitly state 'no update needed' with brief reasoning]"
This is the last acceptance criterion on every task, enforced by the Reviewer. If it's missing, Reviewer blocks with: "Missing mandatory docs/README analysis criterion. Lead must add it before builder proceeds." If it's present but the Builder's action summary is silent on it, Reviewer blocks with: "Docs analysis criterion is present but undocumented."
The result is explicit documentation accountability on every single task - not as a policy document, not as a guideline in a CONTRIBUTING.md nobody reads, but as a hard gate at the end of the workflow.
The updated workflow
Lead
↓ (always)
Explorer
↓ (conditional: significant dep changes or task touches package.json)
Consultant
↓ (always)
Builder
↓ (always)
Reviewer ← enforces docs criterion + all acceptance criteria
The chain is still Lead → Explorer → Builder → Reviewer for the majority of tasks. The Consultant enters when it earns its place. When it does, Builder gets a brief that covers not just what the codebase looks like, but what shifted and what that means.
Getting v1.6.4
npx @cardor/agent-harness-kit init
If you already have a harness in a project, sync the updated agent files:
ahk build
The consultant.md agent file will be added to .claude/agents/, .opencode/agents/, and .codex/agents/ depending on your provider config. The two new MCP tools register automatically. The mandatory docs criterion is baked into the Lead's updated instructions.
Built with agent-harness-kit - provider-agnostic scaffolding for structured multi-agent AI workflows.