From dea77d463f75cfa402bd853f132ccd84311f0578 Mon Sep 17 00:00:00 2001 From: Willem van den Ende Date: Sun, 14 Jun 2026 12:23:52 +0100 Subject: [PATCH] create extension and skill to run yaks --- .pi/extensions/yak-mode-gate.ts | 19 + .pi/skills/yak-tasks/SKILL.md | 84 + transcripts/create-yak-run-skill.html | 4256 +++++++++++++++++++++++++ transcripts/generate-readme.html | 4256 +++++++++++++++++++++++++ 4 files changed, 8615 insertions(+) create mode 100644 .pi/extensions/yak-mode-gate.ts create mode 100644 .pi/skills/yak-tasks/SKILL.md create mode 100644 transcripts/create-yak-run-skill.html create mode 100644 transcripts/generate-readme.html diff --git a/.pi/extensions/yak-mode-gate.ts b/.pi/extensions/yak-mode-gate.ts new file mode 100644 index 0000000..8c13326 --- /dev/null +++ b/.pi/extensions/yak-mode-gate.ts @@ -0,0 +1,19 @@ +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; +import { isToolCallEventType } from "@earendil-works/pi-coding-agent"; + +export default function (pi: ExtensionAPI) { + pi.on("tool_call", async (event, ctx) => { + if (!isToolCallEventType("bash", event)) return; + + const cmd = event.input.command || ""; + const isYxCommand = cmd.includes("yx "); + + // Allow yaks in interactive mode, block in print mode (sub-agents) + if (isYxCommand && ctx.mode === "print") { + return { + block: true, + reason: "yx commands are disabled in print mode. Sub-agents must focus on domain work only.", + }; + } + }); +} diff --git a/.pi/skills/yak-tasks/SKILL.md b/.pi/skills/yak-tasks/SKILL.md new file mode 100644 index 0000000..9468983 --- /dev/null +++ b/.pi/skills/yak-tasks/SKILL.md @@ -0,0 +1,84 @@ +--- +name: yak-tasks +description: Orchestrate sub-agents using yx task tracking. Use when delegating work to sub-agents, tracking task progress, or marking tasks complete. For breaking down problems into tasks, use /skill:problem-breakdown first. +--- + +# Yak Task Orchestration + +Coordinate sub-agent work using the `yx` CLI. The main agent creates tasks and delegates to sub-agents; sub-agents execute domain work without yx CLI access. + +## Workflow + +1. **Break down** → `/skill:problem-breakdown` (creates yaks with context) +2. **Delegate** → sub-agents run on yaks via `pi -p` (blocked from yx CLI) +3. **Track** → `yx list` / `yx show ` +4. **Verify** → run `npm run checks` after sub-agent work +5. **Complete** → `yx done ` + +## Running Sub-Agents + +Sub-agents execute in print mode and are **hard-blocked from using `yx` commands** (see `.pi/extensions/yak-mode-gate.ts`). They receive: +- The yak's `.context.md` (task description) +- `AGENTS.md` (project conventions) +- Domain files to work on +- No yx CLI access + +```bash +# Run a sub-agent on a specific yak +# The sub-agent reads the yak context and executes the work +pi -p "Work on yak: . Read .yaks//.context.md for details." +``` + +## Tracking Progress + +```bash +# List all yaks with hierarchy +yx list + +# Show yak details +yx show + +# Check state directly +cat .yaks//.state +``` + +States: +- `pending` — not yet started +- `in-progress` — being worked on +- `done` — completed + +## Marking Tasks Complete + +```bash +yx done +``` + +Always verify before marking done: +```bash +# 1. Check state +cat .yaks//.state + +# 2. Review what was done +cat .yaks//.context.md + +# 3. Run project checks +npm run checks +``` + +## Sub-Agent Communication + +Sub-agents can read yak state files directly (no yx CLI needed): +```bash +cat .yaks//.name # task name +cat .yaks//.state # current state +cat .yaks//.context.md # task description +cat .yaks//.created.json # creation metadata +``` + +## Best Practices + +- **Delegate after breakdown** — run `/skill:problem-breakdown` first to create structured yaks +- **Verify before marking done** — always run `npm run checks` to catch sub-agent errors +- **Review context** — read `.context.md` to understand what the sub-agent was supposed to do +- **Keep yaks focused** — each yak should be a single file operation or one method implementation +- **Use hierarchy** — parent yaks block children; fix leaves first diff --git a/transcripts/create-yak-run-skill.html b/transcripts/create-yak-run-skill.html new file mode 100644 index 0000000..07fe5ef --- /dev/null +++ b/transcripts/create-yak-run-skill.html @@ -0,0 +1,4256 @@ + + + + + + Session Export + + + + + +
+ + +
+
+
+
+
+ +
+
+ + + + + + + + + + + + + diff --git a/transcripts/generate-readme.html b/transcripts/generate-readme.html new file mode 100644 index 0000000..2267713 --- /dev/null +++ b/transcripts/generate-readme.html @@ -0,0 +1,4256 @@ + + + + + + Session Export + + + + + +
+ + +
+
+
+
+
+ +
+
+ + + + + + + + + + + + +