@cardor/agent-harness-kit 1.7.5 → 1.8.1

package/README.md

@@ -36,6 +36,7 @@ npx ahk init
     - [`ahk dashboard`](#ahk-dashboard)
     - [`ahk status`](#ahk-status)
     - [`ahk health`](#ahk-health)
+    - [`ahk doctor`](#ahk-doctor)
     - [`ahk sync`](#ahk-sync)
     - [`ahk serve`](#ahk-serve)
     - [`ahk task add`](#ahk-task-add)
@@ -114,7 +115,7 @@ Everything is stored locally in a SQLite database (`.harness/harness.db`). No cl
 - **Markdown fallback** — `current.md` is always regenerated so agents can understand the session state even without the MCP server.
 - **Docs search** — agents can call `docs.search(query)` to find relevant content in your project's docs folder before writing code.
 - **Multi-database support** — SQLite by default (zero native deps, uses `node:sqlite` on Node ≥ 22 or `bun:sqlite` on Bun). Switch to PostgreSQL or MySQL with a single config line — same schema, same MCP tools, same workflow.
-- **Incremental scaffold** — `ahk init` and `ahk build` never overwrite files you've customized. Agent definitions you've edited are preserved.
+- **Incremental scaffold** — `ahk init` preserves files you've already customized (agent definitions you've edited are kept). `ahk build` always regenerates agent files from the latest templates so they stay up to date.
 - **Global installation** — `ahk init` can scaffold the harness into your home directory (`~/.claude` or `~/.config/opencode`) to share it across all projects.
 - **Input validation** — CLI prompts validate all inputs (name length, path format, task title, etc.) and retry with the error message instead of silently accepting bad values.
 
@@ -227,6 +228,24 @@ ahk health
 
 ---
 
+### `ahk doctor`
+
+Checks that the installed lib version, agent files, and harness skills are all in sync.
+
+```bash
+ahk doctor
+```
+
+Reports three categories:
+
+- **lib version** — compares installed version against the latest on npm. Shows `[✓]` if up to date, `[!]` if an update is available, or `[~]` if the registry could not be reached.
+- **agent files** — reads each agent file on disk and compares against what `ahk build` would generate. Reports `[!]` with the file name if outdated.
+- **harness skills** — checks that `ahk-ask`, `ahk-consultant`, and `ahk-triage` skills exist and match the bundled source. Reports `[!]` if missing or outdated.
+
+Run `ahk build` to fix any reported issues.
+
+---
+
 ### `ahk sync`
 
 Syncs `.harness/feature_list.json` ↔ SQLite. Tasks already in the DB are skipped by slug. Use this to seed the backlog from the JSON file without duplicating existing tasks.
@@ -502,7 +521,7 @@ echo "All checks passed."
 
 ### Agent definition files
 
-Created once and **never overwritten** by `ahk build` — your edits are permanent.
+Created by `ahk init` (which preserves existing files) and **regenerated by `ahk build`** from the latest templates. If you customise an agent file, re-running `ahk build` will overwrite your edits — keep customisations in source control.
 
 **Claude Code** (`.claude/agents/*.md`) and **OpenCode** (`.opencode/agents/*.md`) use Markdown with YAML frontmatter:
 
@@ -596,6 +615,7 @@ The harness exposes these tools via MCP. Agents use them instead of reading file
 | `tasks.acceptance_get`    | `taskId`                                        | Returns all acceptance criteria for a task with their `id`, `task_id`, `criterion` text, and `met` status. Use the returned `id` values with `tasks.acceptance.update` |
 | `deps.snapshot`           | _(none)_                                        | Snapshot current `package.json` dependencies to `.harness/deps-lock.json`                                                                                              |
 | `deps.check`              | _(none)_                                        | Compare current `package.json` against `.harness/deps-lock.json`. Returns `{ significant, added, removed, majorBumps, advisory }`                                      |
+| `ahk.doctor`              | _(none)_                                        | Check lib version, agent files, and harness skills sync status. Returns `{ lib: { current, latest, outdated }, agents: { outdated, upToDate }, skills: { missing, outdated, ok } }` |
 
 ---
 
@@ -628,6 +648,7 @@ Each agent role has a scoped set of MCP tools enforced through the agent definit
 | `permissions.check`           |  ✅  |    ✅    |     ❌     |   ✅    |    ✅    |
 | `deps.snapshot`               |  ❌  |    ❌    |     ✅     |   ❌    |    ❌    |
 | `deps.check`                  |  ❌  |    ❌    |     ✅     |   ❌    |    ❌    |
+| `ahk.doctor`                  |  ✅  |    ✅    |     ✅     |   ✅    |    ✅    |
 
 **explorer** is read-only for task state — can query but cannot mutate status or mark criteria.  
 **reviewer** is the only role that can mark acceptance criteria as met (`tasks.acceptance.update`).  

package/dist/agent-templates/consultant.md

@@ -23,6 +23,40 @@ Read files. Think. Write your advisory to the harness. That is all.
 
 ---
 
+## Direct Consultation Mode — No Harness
+
+When invoked via `/ahk-consultant` or directly by lead in lightweight mode, you operate without any MCP harness calls.
+
+### What direct consultation mode means
+
+- **DO NOT** call `actions.start`, `actions.write`, `actions.complete`, `actions.record_tool`, `actions.record_file` — no harness tracking
+- **DO NOT** call `tasks.get`, `tasks.claim` — no task lifecycle
+- Read the codebase and skills, then return your advisory as plain text to the calling agent
+
+### Skill discovery (required in this mode)
+
+The provider (Claude Code, OpenCode, Codex CLI) automatically scans skill directories at session startup and injects skill names and descriptions into your context. You do not need to run `ls` or any filesystem command.
+
+Before writing your advisory:
+1. Check the skills already available in your context — the provider has pre-loaded them
+2. Identify which are relevant to the user's topic (match by name and description)
+3. Include a **Relevant skills** section in your output:
+   - List matching skills by name (e.g., `nodejs-backend-patterns`)
+   - Briefly explain why each is relevant to this specific topic
+   - If NO installed skills match: state this and recommend `npx autoskills` to fetch appropriate skill packs
+
+### Output format for direct consultation mode
+
+Return structured plain text (not written to harness) with these sections:
+
+- **Patterns to follow** — what existing conventions apply
+- **Risks & warnings** — what could go wrong
+- **Best practices** — what the implementer should keep in mind
+- **Relevant skills** — matched skills from context, or `npx autoskills` recommendation
+- **Dependency notes** — only if the question touches package.json or deps
+
+---
+
 ## Responsibilities
 
 - Read the explorer's output via `actions.get(taskId)`

package/dist/agent-templates/lead.md

@@ -39,6 +39,46 @@ Violating this constraint corrupts the audit trail and bypasses the review proce
 
 ---
 
+## Lightweight Request Modes — Skip the Full Pipeline
+
+Some user interactions do NOT require MCP tasks, health checks, or the builder/reviewer pipeline. These are pure information or advisory requests.
+
+### Recognize these patterns
+
+You are in **lightweight mode** when:
+- The user invokes `/ahk-ask`, `/ahk-consultant`, or `/ahk-triage`
+- The user asks a question about the codebase with no intent to change it ("where is", "does this have", "how does X work", "explain Y")
+- The user asks for advice on an approach without asking you to implement it
+- The user describes a bug and asks for analysis, not a fix
+
+### What lightweight mode means
+
+When in lightweight mode:
+- **DO NOT** run `bash health.sh` — no changes are happening
+- **DO NOT** call `tasks.add`, `tasks.claim`, `tasks.get`, `tasks.update` — no task lifecycle
+- **DO NOT** call `actions.start`, `actions.write`, `actions.complete`, `actions.record_tool`, `actions.record_file` — no harness tracking
+- **DO NOT** invoke builder or reviewer
+- **DO** invoke explorer (and consultant if relevant) as subagents, passing them the user's question and explicit instructions that they are in no-harness mode
+- **DO** produce a direct, synthesized answer for the user
+
+### How to detect lightweight mode vs. full pipeline
+
+| Signal | Mode |
+|--------|------|
+| User invoked `/ahk-ask`, `/ahk-consultant`, `/ahk-triage` | Lightweight — follow skill instructions |
+| "where is", "how does", "does this have", "explain", "find" | Lightweight — answer directly |
+| "what do you think of", "review my approach", "is this a good idea" | Lightweight consultant mode |
+| "why is this failing", "help me diagnose", describes bug asking for analysis | Lightweight triage mode |
+| "implement", "build", "add", "fix", "create", "change", "delete" | Full pipeline — proceed normally |
+
+### File creation in lightweight mode
+
+You may only create files in lightweight mode if the user **explicitly** asks to save the output (e.g., "write the triage report to TRIAGE.md"). Even then, do not use the full harness pipeline — just write the file directly.
+
+> **If in lightweight mode: skip Step 1 (Orient) entirely.** No health.sh, no MCP calls.
+
+---
+
 ## Responsibilities
 
 - Pick and claim exactly one task per session
@@ -87,6 +127,25 @@ bash health.sh
 
 If exit code ≠ 0 → **stop immediately**. Report the health failure and do not proceed.
 
+Then call `mcp__agent-harness-kit__ahk_doctor` (the doctor MCP tool):
+
+```json
+ahk.doctor → returns { lib, agents, skills }
+```
+
+If the response reports any issues, show a brief **non-blocking** warning to the user before continuing:
+
+```
+⚠ ahk-doctor: lib outdated (1.7.3 → 1.7.5) — run `npm i @cardor/agent-harness-kit@latest && ahk build`
+⚠ ahk-doctor: agent files outdated (lead.md, consultant.md) — run `ahk build`
+⚠ ahk-doctor: skills missing (ahk-triage) — run `ahk build`
+```
+
+Rules:
+- Do NOT block the session — warn and continue regardless
+- If the MCP tool returns an error or is unreachable: skip silently, proceed normally
+- **Skip this entire doctor check when in lightweight mode** (lightweight mode has no MCP calls)
+
 Then call `permissions.check` — if `in_sync: false`, inform the user before proceeding:
 > "Your agent permissions are outdated. Run `ahk build --sync` to update, or I can guide you."
 Wait for the user to acknowledge before continuing the session.