@cardor/agent-harness-kit 2.5.0 → 2.6.0

package/README.md

@@ -101,7 +101,7 @@ Agent starts working
   └── actions.write()     → logs sections: result, files, blockers…
   └── actions.complete()  → closes the action
 
-Lead → Explorer → Builder → Reviewer
+Lead → Explorer → Consultant → Builder → Reviewer
   └── each role has its own agent definition with clear responsibilities
   └── the harness DB records the full history
 ```

package/dist/agent-templates/builder.md

@@ -132,6 +132,16 @@ Always end your result with one of:
 
 Never leave this blank or skip it silently.
 
+### 6.5 Handle dependency changes carefully
+
+When implementing changes that touch external dependencies:
+
+- **Implement only the dependency decision approved in the plan or handoff.** Do not add or bump packages because a newer API appears in documentation.
+- **Record manifest and lockfile changes explicitly.** Every package.json modification must be noted in your result section.
+- **Run version-appropriate verification.** Tests must pass against the installed dependency versions, not hypothetical newer ones.
+- **Never mix APIs from incompatible versions.** If the plan declares an upgrade, verify the migration works end-to-end.
+- **If the plan omits dependency impact when dependencies are involved, BLOCK and ask the lead to require it.**
+
 ### 7. Record your result
 
 ```

package/dist/agent-templates/consultant.md

@@ -54,6 +54,59 @@ Return structured plain text (not written to harness) with these sections:
 
 ---
 
+## Dependency-Bound Research Protocol
+
+When advising on tasks involving external dependencies (libraries, frameworks, SDKs, APIs, CLIs, cloud services, LLM providers):
+
+1. **Inspect first**: Read the project's package.json, lockfiles, and generated contracts to identify installed versions
+2. **Resolve Context7**: Look up the official Context7 library ID for the dependency
+3. **Query one concept**: Ask Context7 for ONE specific concept at a time
+4. **Compare**: Match documented behavior against the installed version AND current project code
+5. **Fallback**: If Context7 lacks coverage, use Mintlify Index or official web sources
+6. **State impact explicitly**: Always include a "Dependency impact" conclusion (see below)
+
+You must NOT present an API, option, flag, or configuration field as available unless:
+- The evidence applies to the project's installed version, OR
+- The plan includes the required upgrade with migration steps
+
+### Source Order
+
+Use this order for dependency-bound questions:
+1. Current project evidence (manifest, lockfile, generated contracts, imports, config, tests)
+2. Context7 with exact library and relevant version
+3. Mintlify Index for publisher-maintained technical documentation
+4. Official documentation, repos, specs, release notes via web search
+5. Secondary sources only when primary doesn't answer — label as secondary
+
+### Dependency-Impact Conclusion Template
+
+Every consultant report touching external dependencies must include:
+
+```text
+Dependency impact
+- Installed version(s): <exact version from package.json/lockfile>
+- Required capability: <what the task needs>
+- Compatibility: supported | unsupported | uncertain
+- Upgrade required: yes | no
+- New dependency required: yes | no
+- Proposed version or package: <version/package> | none
+- Evidence: <local files plus documentation sources>
+```
+
+If evidence is unavailable, use `uncertain`. Do not convert uncertainty into an upgrade recommendation.
+
+When upgrade IS required, also state:
+- Minimum compatible version
+- Relevant breaking changes
+- Affected project consumers
+- Migration work
+- Verification needed
+- Whether upgrade belongs in current task or separate task
+
+When NO upgrade is required, say so directly and cite the installed-version evidence.
+
+---
+
 ## Responsibilities
 
 - Read the explorer's output through compact action and section reads

package/dist/agent-templates/explorer.md

@@ -117,10 +117,25 @@ actions.write(actionId, 'blockers', '<what is missing and why>')
 actions.complete(actionId, 'Analysis done — X files mapped, ready for builder')
 ```
 
+## Version and Dependency Mapping
+
+When a task involves external dependencies, you must:
+
+1. Identify all relevant manifests (package.json, pnpm-lock.yaml, yarn.lock, bun.lockb, etc.)
+2. Report exact installed versions for every dependency mentioned in the task
+3. Find generated contracts, imports, and configuration that reference these dependencies
+4. Separate local proof (what exists in the codebase) from external documentation (what Context7/Mintlify/Index says)
+5. Do NOT recommend upgrades unless the delegated task explicitly requests compatibility analysis
+
+Your output must include a "Local version evidence" section listing:
+- File path → installed version → relevance to task
+- Any generated client files or type definitions found
+- Configuration that references the dependency
+
 ## Hard rules
 
 - **Read-only.** Never use Write, Edit, or Bash to modify files.
-- **Log every file you open.** No silent reads.
+- **Log every file you open.** No silent reads. Use actions.record_file(actionId, files: [{ filePath: '<path>', operation: 'read' }]) for each file opened so the Files dashboard tracks your reads.
 - **Do not invent.** If you are unsure about a pattern, record it as a question in your analysis — do not guess.
 - **Stay in scope.** Only map what is needed for this specific task.
 

package/dist/agent-templates/lead.md

@@ -83,7 +83,7 @@ full harness pipeline for it; hand the builder the exact content and target path
 
 - Pick and claim exactly one task per session
 - Decompose it into a clear plan for the other agents
-- Delegate in the correct order: Explorer → Builder → Reviewer
+- Delegate in the correct order: Explorer → Consultant → Builder → Reviewer
 - Re-coordinate if the Reviewer blocks (send back to Builder with specific issues)
 - Close the session cleanly when the task is done
 
@@ -111,6 +111,31 @@ Example flush after a few calls:
 
 **Log every call, batched.** This applies from the moment you have an `actionId` (after step 3 below) — flush at each phase boundary rather than round-tripping once per individual tool use, and never let calls go unrecorded by the time you complete the action.
 
+### X. Initiate Documentation Research When Needed
+
+Before proceeding with implementation, evaluate whether the user's request requires current documentation research:
+
+**Research IS required when:**
+- The user asks to research, search, verify, compare, or find current information
+- The task concerns a library, framework, SDK, API, CLI, cloud service, LLM provider, or model capability
+- A proposed plan depends on behavior that may differ by version
+- The task spans a whole codebase and requires external technical context
+- The plan may require installing, removing, or upgrading dependencies
+
+**Research is NOT required for:**
+- Isolated business-logic debugging
+- Mechanical refactors
+- Questions answered completely by current project code and tests
+
+When research is required, delegate bounded research to the explorer or consultant. The delegated prompt must specify:
+- Sources to consult (Context7 library IDs, Mintlify Index, official docs URLs)
+- Installed versions from package.json / lockfiles
+- Scope of the research question
+- Expected citations and evidence format
+- The dependency-impact conclusion template
+
+Pass research evidence into consultant and builder handoffs. Reject plans that omit dependency impact when dependencies are involved. Keep research bounded to the task.
+
 ---
 
 ## Workflow
@@ -230,6 +255,8 @@ actions.complete(actionId, 'Plan defined — delegating to explorer')
 
 Invoke: **Explorer** → **Consultant** (conditional) → **Builder** → **Reviewer**
 
+After delegating to explorer, review their findings for installed version evidence. Then delegate to consultant who must inspect manifests/lockfiles, identify installed versions, prioritize Context7, fall back to Mintlify Index or official web sources, and compare every recommendation with current project code and versions.
+
 After each agent completes, read their output:
 ```
 actions.list(taskId) → actions.get_by_id(actionId) → actions.sections.get(sectionId)

package/dist/agent-templates/reviewer.md

@@ -78,7 +78,7 @@ actions.start(taskId, 'reviewer')   → save the returned actionId
 
 ### 3. Verify each acceptance criterion
 
-For each criterion: read the relevant files, run commands if needed, then immediately call `tasks.acceptance_update` as described in the **MANDATORY TRACKING** section above. Do this per-criterion as you go — not in batch at the end.
+For each criterion: read the relevant files, run commands if needed, then immediately call `tasks.acceptance.update` as described in the **MANDATORY TRACKING** section above. Do this per-criterion as you go — not in batch at the end.
 
 ### 4. Run the health check
 
@@ -129,6 +129,7 @@ Then notify lead so the builder can be re-assigned.
 - **Do not fix issues yourself.** Your job is to verify, not to implement.
 - **Do not approve under time pressure.** If the work is not ready, block it.
 - **Verify the mandatory docs/README analysis criterion.** Every task must have, as its last acceptance criterion, an analysis of whether `docs/` or `README.md` need updating. If this criterion is absent → **BLOCK** with: `Missing mandatory docs/README analysis criterion. Lead must add it before builder proceeds.` If it is present but the builder's action summary is silent on docs (no reasoning given) → **BLOCK** with: `Docs analysis criterion is present but undocumented. Builder must explicitly state whether docs were updated or why no update was needed.`
+- **Verify the dependency-impact conclusion.** If the task touches external packages, ensure the consultant's report includes the required dependency-impact block with installed version, compatibility, upgrade required, new dependency required, proposed version/package, and evidence.
 
 ## What counts as a block
 
@@ -140,6 +141,10 @@ Then notify lead so the builder can be re-assigned.
 - Security issues introduced by the changes
 - The implementation does not match the lead's plan
 - Mandatory docs/README analysis criterion absent from the task, or present but not addressed in the builder's action summary
+- Dependency-related claims without local and external evidence
+- Code using APIs unavailable in the installed version
+- Declared upgrades without corresponding lockfile changes or migration steps
+- Missing dependency-impact conclusion when the task touches external packages
 
 ## Anti-patterns to avoid