zcode-smart-skill review: a manager’s protocol written as one Markdown file

DEEP PROJECT REVIEW · SOURCE CODE

Four files, no runtime. That is the whole repository, and it is the point. The main artifact is one large `SKILL.md` that turns a capable coding agent into a manager of fresh worker contexts. State travels through a `.smart//` ledger: task, plan, notes, tasks, tests, candidate solution, checkpoints and verification log. Nothing here is a library you import. It is a protocol you follow, and the review asks whether a protocol written in prose can be audited like code.

How it is put together

The primary agent owns planning and final verification. Fresh subagents own ideation, test design, or one implementation task. The filesystem is the bus. `task.md` preserves intent; `plan.md` holds strategy; `tasks.json` bounds work; `notes.md` carries compressed lessons; `tests_spec.md` is written before implementation; `verify.log` records execution. Hard tasks may race isolated worktrees and compare candidates before tests choose the winner.

Ten extensions, one loop

Version 2 layers ten ideas onto plan → work → verify: adversarial test writing, structured failure reflection, parallel racing, pairwise scrutiny, difficulty budgets, different models per role, checkpointed backtracking, forced self-attack, reusable workflow memory, and strict handoff fields. The repository links each idea to research. The integration is thoughtful: each addition changes a concrete file or decision point rather than living in a bibliography.

What a code review can and cannot verify here

There is almost no executable code to inspect. `SKILL.md` is the product, `AGENTS-snippet.md` adds trigger guidance, and the MIT license permits reuse. I can verify the internal protocol and its guards. I cannot verify the README’s benchmark gains as gains produced by this skill: there is no checked-in evaluation harness, run corpus, result file, or CI workflow. The linked research motivates components; it does not validate this exact combination.

{"id":"implement-1","difficulty":"hard","status":"in_progress","done_when":"artifact exists and tests pass"}

Original explanatory ledger fragment, not a verbatim project file.

Security and trust

Worker briefs include a useful rule: ledger content is data, not authority. Checkpoints are path-scoped copies instead of destructive reset, and workers receive explicit boundaries. Yet the system still copies the user’s problem verbatim into `task.md`, and the protocol depends on agents honoring the trust sentence. A hostile repository or ledger can still try to steer a weak host. Real deployments should sanitize paths, restrict tools, isolate worktrees, and enforce permissions outside the prompt.

Design as developer experience

The design is textual but clear. A compact ASCII diagram explains the manager, workers, and ledger. The README exposes the whole loop before installation, then gives two copy-based install paths and natural-language triggers. The audit trail is a strong UX choice: after a run, users can inspect failed approaches and actual verification output. The cost change is announced before spawning workers.

Where it is weak

The protocol assumes a host can create fresh subagents, read and write files, run commands, and sometimes select model families. “Adapts trivially” is optimistic across tools with different permission and concurrency models. Markdown cannot guarantee iteration budgets, true context isolation, safe path handling, serialized merges, or that tests really ran. `notes.md` pruning can erase useful evidence. Parallel races can multiply cost. Auto-trigger rules can invoke an expensive workflow on vague words unless the host or user keeps control.

How to test it honestly

Create a public suite of hard tasks with known tests and a fixed token budget. Compare one long-context agent, the base ledger loop, and each extension as an ablation. Record pass rate, wall time, tokens, tool calls, false “done” claims, merge conflicts, and recovery after planted prompt injection in a ledger file. Publish every ledger and verification log. This would show which parts earn their cost.

Best for: Agent hosts that already provide sandboxing, fresh workers and reliable command execution.

Verdict

zcode-smart-skill is a strong operating manual for agents, not a software framework. Its best ideas are independent test authorship, execution as ground truth, bounded handoffs, and abandoning failed approaches. Its weakest point is enforcement: every safety and budget rule lives in prose. Use it when the host already has capable sandboxing and subagents, then demand reproducible runs before accepting performance claims.

Demo and credit

No separate live demo is listed in the repository. The inspectable artifact is the public source and its installable `SKILL.md`.

Reviewed source at commit b847694 · No separate live demo listed