@laurentenhoor/devclaw 0.1.0

package/dist/lib/setup/agent.d.ts

@@ -0,0 +1,14 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+/**
+ * Create a new agent via `openclaw agents add`.
+ * Cleans up .git and BOOTSTRAP.md from the workspace, updates display name.
+ */
+export declare function createAgent(api: OpenClawPluginApi, name: string, channelBinding?: "telegram" | "whatsapp" | null): Promise<{
+    agentId: string;
+    workspacePath: string;
+}>;
+/**
+ * Resolve workspace path from an agent ID via OpenClaw config API.
+ */
+export declare function resolveWorkspacePath(api: OpenClawPluginApi, agentId: string): string;
+//# sourceMappingURL=agent.d.ts.map

package/dist/lib/setup/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../lib/setup/agent.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAI7D;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,GAC9C,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBrD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQpF"}

package/dist/lib/setup/agent.js

@@ -0,0 +1,72 @@
+/**
+ * setup/agent.ts — Agent creation and workspace resolution.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import fs from "node:fs/promises";
+import path from "node:path";
+const execFileAsync = promisify(execFile);
+/**
+ * Create a new agent via `openclaw agents add`.
+ * Cleans up .git and BOOTSTRAP.md from the workspace, updates display name.
+ */
+export async function createAgent(api, name, channelBinding) {
+    const agentId = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+    const args = ["agents", "add", agentId, "--non-interactive"];
+    if (channelBinding)
+        args.push("--bind", channelBinding);
+    try {
+        await execFileAsync("openclaw", args, { timeout: 30_000 });
+    }
+    catch (err) {
+        throw new Error(`Failed to create agent "${name}": ${err.message}`);
+    }
+    const workspacePath = resolveWorkspacePath(api, agentId);
+    await cleanupWorkspace(workspacePath);
+    await updateAgentDisplayName(api, agentId, name);
+    return { agentId, workspacePath };
+}
+/**
+ * Resolve workspace path from an agent ID via OpenClaw config API.
+ */
+export function resolveWorkspacePath(api, agentId) {
+    const config = api.runtime.config.loadConfig();
+    const agent = config.agents?.list?.find((a) => a.id === agentId);
+    if (!agent?.workspace) {
+        throw new Error(`Agent "${agentId}" not found in openclaw.json or has no workspace configured.`);
+    }
+    return agent.workspace;
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+async function cleanupWorkspace(workspacePath) {
+    // openclaw agents add creates a .git dir and BOOTSTRAP.md — remove them
+    try {
+        await fs.rm(path.join(workspacePath, ".git"), { recursive: true });
+    }
+    catch { /* may not exist */ }
+    try {
+        await fs.unlink(path.join(workspacePath, "BOOTSTRAP.md"));
+    }
+    catch { /* may not exist */ }
+}
+async function updateAgentDisplayName(api, agentId, name) {
+    if (name === agentId)
+        return;
+    try {
+        const config = api.runtime.config.loadConfig();
+        const agent = config.agents?.list?.find((a) => a.id === agentId);
+        if (agent) {
+            agent.name = name;
+            await api.runtime.config.writeConfigFile(config);
+        }
+    }
+    catch (err) {
+        console.warn(`Warning: Could not update display name: ${err.message}`);
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/lib/setup/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../lib/setup/agent.ts"],"names":[],"mappings":"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"}

package/dist/lib/setup/config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * setup/config.ts — Plugin config writer (openclaw.json).
+ *
+ * Handles: model level config, tool restrictions, subagent cleanup.
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+type ModelConfig = {
+    dev: Record<string, string>;
+    qa: Record<string, string>;
+};
+/**
+ * Write DevClaw model level config to openclaw.json plugins section.
+ *
+ * Also configures:
+ * - Tool restrictions (deny sessions_spawn, sessions_send) for DevClaw agents
+ * - Subagent cleanup interval (30 days) to keep development sessions alive
+ *
+ * Read-modify-write to preserve existing config.
+ */
+export declare function writePluginConfig(api: OpenClawPluginApi, models: ModelConfig, agentId?: string, projectExecution?: "parallel" | "sequential"): Promise<void>;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/setup/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../lib/setup/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG7D,KAAK,WAAW,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAE/E;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,UAAU,GAAG,YAAY,GAC3C,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/lib/setup/config.js

@@ -0,0 +1,67 @@
+import { HEARTBEAT_DEFAULTS } from "../services/heartbeat.js";
+/**
+ * Write DevClaw model level config to openclaw.json plugins section.
+ *
+ * Also configures:
+ * - Tool restrictions (deny sessions_spawn, sessions_send) for DevClaw agents
+ * - Subagent cleanup interval (30 days) to keep development sessions alive
+ *
+ * Read-modify-write to preserve existing config.
+ */
+export async function writePluginConfig(api, models, agentId, projectExecution) {
+    const config = api.runtime.config.loadConfig();
+    ensurePluginStructure(config);
+    config.plugins.entries.devclaw.config.models = models;
+    if (projectExecution) {
+        config.plugins.entries.devclaw.config.projectExecution = projectExecution;
+    }
+    ensureHeartbeatDefaults(config);
+    configureSubagentCleanup(config);
+    if (agentId) {
+        addToolRestrictions(config, agentId);
+    }
+    await api.runtime.config.writeConfigFile(config);
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+function ensurePluginStructure(config) {
+    if (!config.plugins)
+        config.plugins = {};
+    const plugins = config.plugins;
+    if (!plugins.entries)
+        plugins.entries = {};
+    const entries = plugins.entries;
+    if (!entries.devclaw)
+        entries.devclaw = {};
+    const devclaw = entries.devclaw;
+    if (!devclaw.config)
+        devclaw.config = {};
+}
+function configureSubagentCleanup(config) {
+    if (!config.agents)
+        config.agents = {};
+    const agents = config.agents;
+    if (!agents.defaults)
+        agents.defaults = {};
+    const defaults = agents.defaults;
+    if (!defaults.subagents)
+        defaults.subagents = {};
+    defaults.subagents.archiveAfterMinutes = 43200;
+}
+function addToolRestrictions(config, agentId) {
+    const agent = config.agents?.list?.find((a) => a.id === agentId);
+    if (agent) {
+        if (!agent.tools)
+            agent.tools = {};
+        agent.tools.deny = ["sessions_spawn", "sessions_send"];
+        delete agent.tools.allow;
+    }
+}
+function ensureHeartbeatDefaults(config) {
+    const devclaw = config.plugins.entries.devclaw.config;
+    if (!devclaw.work_heartbeat) {
+        devclaw.work_heartbeat = { ...HEARTBEAT_DEFAULTS };
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/lib/setup/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../lib/setup/config.ts"],"names":[],"mappings":"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"}

package/dist/lib/setup/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * setup/index.ts — DevClaw setup orchestrator.
+ *
+ * Coordinates: agent creation → model config → workspace scaffolding.
+ * Used by both the `setup` tool and the `openclaw devclaw setup` CLI command.
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+export type ModelConfig = {
+    dev: Record<string, string>;
+    qa: Record<string, string>;
+};
+export type SetupOpts = {
+    /** OpenClaw plugin API for config access. */
+    api: OpenClawPluginApi;
+    /** Create a new agent with this name. Mutually exclusive with agentId. */
+    newAgentName?: string;
+    /** Channel binding for new agent. Only used when newAgentName is set. */
+    channelBinding?: "telegram" | "whatsapp" | null;
+    /** Migrate channel binding from this agent ID. Only used when newAgentName and channelBinding are set. */
+    migrateFrom?: string;
+    /** Use an existing agent by ID. Mutually exclusive with newAgentName. */
+    agentId?: string;
+    /** Override workspace path (auto-detected from agent if not given). */
+    workspacePath?: string;
+    /** Model overrides per role.level. Missing levels use defaults. */
+    models?: {
+        dev?: Partial<Record<string, string>>;
+        qa?: Partial<Record<string, string>>;
+    };
+    /** Plugin-level project execution mode: parallel or sequential. Default: parallel. */
+    projectExecution?: "parallel" | "sequential";
+};
+export type SetupResult = {
+    agentId: string;
+    agentCreated: boolean;
+    workspacePath: string;
+    models: ModelConfig;
+    filesWritten: string[];
+    warnings: string[];
+    bindingMigrated?: {
+        from: string;
+        channel: "telegram" | "whatsapp";
+    };
+};
+/**
+ * Run the full DevClaw setup.
+ *
+ * 1. Create agent (optional) or resolve existing workspace
+ * 2. Merge model config and write to openclaw.json
+ * 3. Write workspace files (AGENTS.md, HEARTBEAT.md, roles, memory)
+ */
+export declare function runSetup(opts: SetupOpts): Promise<SetupResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/setup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/setup/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAO7D,MAAM,MAAM,WAAW,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAEtF,MAAM,MAAM,SAAS,GAAG;IACtB,6CAA6C;IAC7C,GAAG,EAAE,iBAAiB,CAAC;IACvB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,cAAc,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAAC;IAChD,0GAA0G;IAC1G,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,MAAM,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;KAAE,CAAC;IACzF,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;CAC9C,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,CAAC,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,UAAU,GAAG,UAAU,CAAC;KAClC,CAAC;CACH,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAYpE"}

package/dist/lib/setup/index.js

@@ -0,0 +1,68 @@
+import { DEFAULT_MODELS } from "../tiers.js";
+import { migrateChannelBinding } from "../binding-manager.js";
+import { createAgent, resolveWorkspacePath } from "./agent.js";
+import { writePluginConfig } from "./config.js";
+import { scaffoldWorkspace } from "./workspace.js";
+/**
+ * Run the full DevClaw setup.
+ *
+ * 1. Create agent (optional) or resolve existing workspace
+ * 2. Merge model config and write to openclaw.json
+ * 3. Write workspace files (AGENTS.md, HEARTBEAT.md, roles, memory)
+ */
+export async function runSetup(opts) {
+    const warnings = [];
+    const { agentId, workspacePath, agentCreated, bindingMigrated } = await resolveOrCreateAgent(opts, warnings);
+    const models = buildModelConfig(opts.models);
+    await writePluginConfig(opts.api, models, agentId, opts.projectExecution);
+    const filesWritten = await scaffoldWorkspace(workspacePath);
+    return { agentId, agentCreated, workspacePath, models, filesWritten, warnings, bindingMigrated };
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+async function resolveOrCreateAgent(opts, warnings) {
+    if (opts.newAgentName) {
+        const { agentId, workspacePath } = await createAgent(opts.api, opts.newAgentName, opts.channelBinding);
+        const bindingMigrated = await tryMigrateBinding(opts, agentId, warnings);
+        return { agentId, workspacePath, agentCreated: true, bindingMigrated };
+    }
+    if (opts.agentId) {
+        const workspacePath = opts.workspacePath ?? resolveWorkspacePath(opts.api, opts.agentId);
+        return { agentId: opts.agentId, workspacePath, agentCreated: false };
+    }
+    if (opts.workspacePath) {
+        return { agentId: "unknown", workspacePath: opts.workspacePath, agentCreated: false };
+    }
+    throw new Error("Setup requires either newAgentName, agentId, or workspacePath");
+}
+async function tryMigrateBinding(opts, agentId, warnings) {
+    if (!opts.migrateFrom || !opts.channelBinding)
+        return undefined;
+    try {
+        await migrateChannelBinding(opts.api, opts.channelBinding, opts.migrateFrom, agentId);
+        return { from: opts.migrateFrom, channel: opts.channelBinding };
+    }
+    catch (err) {
+        warnings.push(`Failed to migrate binding from "${opts.migrateFrom}": ${err.message}`);
+        return undefined;
+    }
+}
+function buildModelConfig(overrides) {
+    const dev = { ...DEFAULT_MODELS.dev };
+    const qa = { ...DEFAULT_MODELS.qa };
+    if (overrides?.dev) {
+        for (const [level, model] of Object.entries(overrides.dev)) {
+            if (model)
+                dev[level] = model;
+        }
+    }
+    if (overrides?.qa) {
+        for (const [level, model] of Object.entries(overrides.qa)) {
+            if (model)
+                qa[level] = model;
+        }
+    }
+    return { dev, qa };
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/setup/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/setup/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/setup/workspace.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Write all workspace files for a DevClaw agent.
+ * Returns the list of files that were written (skips files that already exist).
+ */
+export declare function scaffoldWorkspace(workspacePath: string): Promise<string[]>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/lib/setup/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../lib/setup/workspace.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuChF"}

package/dist/lib/setup/workspace.js

@@ -0,0 +1,69 @@
+/**
+ * setup/workspace.ts — Workspace file scaffolding.
+ *
+ * Writes AGENTS.md, HEARTBEAT.md, default role instructions, and projects.json.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { AGENTS_MD_TEMPLATE, HEARTBEAT_MD_TEMPLATE, DEFAULT_DEV_INSTRUCTIONS, DEFAULT_QA_INSTRUCTIONS, } from "../templates.js";
+/**
+ * Write all workspace files for a DevClaw agent.
+ * Returns the list of files that were written (skips files that already exist).
+ */
+export async function scaffoldWorkspace(workspacePath) {
+    const filesWritten = [];
+    // AGENTS.md (backup existing)
+    await backupAndWrite(path.join(workspacePath, "AGENTS.md"), AGENTS_MD_TEMPLATE);
+    filesWritten.push("AGENTS.md");
+    // HEARTBEAT.md
+    await backupAndWrite(path.join(workspacePath, "HEARTBEAT.md"), HEARTBEAT_MD_TEMPLATE);
+    filesWritten.push("HEARTBEAT.md");
+    // projects/projects.json
+    const projectsDir = path.join(workspacePath, "projects");
+    await fs.mkdir(projectsDir, { recursive: true });
+    const projectsJsonPath = path.join(projectsDir, "projects.json");
+    if (!await fileExists(projectsJsonPath)) {
+        await fs.writeFile(projectsJsonPath, JSON.stringify({ projects: {} }, null, 2) + "\n", "utf-8");
+        filesWritten.push("projects/projects.json");
+    }
+    // projects/roles/default/ (fallback role instructions)
+    const defaultRolesDir = path.join(projectsDir, "roles", "default");
+    await fs.mkdir(defaultRolesDir, { recursive: true });
+    const devRolePath = path.join(defaultRolesDir, "dev.md");
+    if (!await fileExists(devRolePath)) {
+        await fs.writeFile(devRolePath, DEFAULT_DEV_INSTRUCTIONS, "utf-8");
+        filesWritten.push("projects/roles/default/dev.md");
+    }
+    const qaRolePath = path.join(defaultRolesDir, "qa.md");
+    if (!await fileExists(qaRolePath)) {
+        await fs.writeFile(qaRolePath, DEFAULT_QA_INSTRUCTIONS, "utf-8");
+        filesWritten.push("projects/roles/default/qa.md");
+    }
+    // log/ directory (audit.log created on first write)
+    const logDir = path.join(workspacePath, "log");
+    await fs.mkdir(logDir, { recursive: true });
+    return filesWritten;
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+async function backupAndWrite(filePath, content) {
+    try {
+        await fs.access(filePath);
+        await fs.copyFile(filePath, filePath + ".bak");
+    }
+    catch {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+    }
+    await fs.writeFile(filePath, content, "utf-8");
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/lib/setup/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../lib/setup/workspace.ts"],"names":[],"mappings":"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"}

package/dist/lib/templates.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared templates for workspace files.
+ * Used by setup and project_register.
+ */
+export declare const DEFAULT_DEV_INSTRUCTIONS = "# DEV Worker Instructions\n\n## Context You Receive\n\nWhen you start work, you're given:\n\n- **Issue:** number, title, body, URL, labels, state\n- **Comments:** full discussion thread on the issue\n- **Assignees:** who's assigned\n- **Timestamps:** created, updated dates\n- **Project:** repo path, base branch, project name\n\nRead the comments carefully \u2014 they often contain clarifications, decisions, or scope changes that aren't in the original issue body.\n\n## Your Job\n\n- Work in a git worktree (never switch branches in the main repo)\n- Run tests before completing\n- Create an MR/PR to the base branch and merge it\n- **IMPORTANT:** Do NOT use closing keywords in PR/MR descriptions (no \"Closes #X\", \"Fixes #X\", \"Resolves #X\"). Use \"As described in issue #X\" or \"Addresses issue #X\" instead. DevClaw manages issue state \u2014 auto-closing bypasses QA.\n- Clean up the worktree after merging\n- When done, call work_finish with role \"dev\", result \"done\", and a brief summary\n- If you discover unrelated bugs, call task_create to file them\n- Do NOT call work_start, status, health, or project_register\n";
+export declare const DEFAULT_QA_INSTRUCTIONS = "# QA Worker Instructions\n\n- Pull latest from the base branch\n- Run tests and linting\n- Verify the changes address the issue requirements\n- Check for regressions in related functionality\n- **Always** call task_comment with your review findings \u2014 even if everything looks good, leave a brief summary of what you checked\n- When done, call work_finish with role \"qa\" and one of:\n  - result \"pass\" if everything looks good\n  - result \"fail\" with specific issues if problems found\n  - result \"refine\" if you need human input to decide\n- If you discover unrelated bugs, call task_create to file them\n- Do NOT call work_start, status, health, or project_register\n";
+export declare const AGENTS_MD_TEMPLATE = "# AGENTS.md - Development Orchestration (DevClaw)\n\n## If You Are a Sub-Agent (DEV/QA Worker)\n\nSkip the orchestrator section. Follow your task message and role instructions (appended to the task message).\n\n### Conventions\n\n- Conventional commits: `feat:`, `fix:`, `chore:`, `refactor:`, `test:`, `docs:`\n- Include issue number: `feat: add user authentication (#12)`\n- Branch naming: `feature/<id>-<slug>` or `fix/<id>-<slug>`\n- **DEV always works in a git worktree** (never switch branches in the main repo)\n- **DEV must merge to base branch** before announcing completion\n- **Do NOT use closing keywords in PR/MR descriptions** (no \"Closes #X\", \"Fixes #X\", \"Resolves #X\"). Use \"As described in issue #X\" or \"Addresses issue #X\". DevClaw manages issue state \u2014 auto-closing bypasses QA.\n- **QA tests on the deployed version** and inspects code on the base branch\n- **QA always calls task_comment** with review findings before completing\n- Always run tests before completing\n\n### Completing Your Task\n\nWhen you are done, **call `work_finish` yourself** \u2014 do not just announce in text.\n\n- **DEV done:** `work_finish({ role: \"dev\", result: \"done\", projectGroupId: \"<from task message>\", summary: \"<brief summary>\" })`\n- **QA pass:** `work_finish({ role: \"qa\", result: \"pass\", projectGroupId: \"<from task message>\", summary: \"<brief summary>\" })`\n- **QA fail:** `work_finish({ role: \"qa\", result: \"fail\", projectGroupId: \"<from task message>\", summary: \"<specific issues>\" })`\n- **QA refine:** `work_finish({ role: \"qa\", result: \"refine\", projectGroupId: \"<from task message>\", summary: \"<what needs human input>\" })`\n\nThe `projectGroupId` is included in your task message.\n\n### Filing Follow-Up Issues\n\nIf you discover unrelated bugs or needed improvements during your work, call `task_create` to file them:\n\n`task_create({ projectGroupId: \"<from task message>\", title: \"Bug: ...\", description: \"...\" })`\n\n### Tools You Should NOT Use\n\nThese are orchestrator-only tools. Do not call them:\n- `work_start`, `status`, `health`, `project_register`\n\n---\n\n## Orchestrator\n\nYou are a **development orchestrator**. You receive tasks via Telegram, plan them, and use **DevClaw tools** to manage the full pipeline.\n\n### DevClaw Tools\n\nAll orchestration goes through these tools. You do NOT manually manage sessions, labels, or projects.json.\n\n| Tool | What it does |\n|---|---|\n| `project_register` | One-time project setup: creates labels, scaffolds role files, adds to projects.json |\n| `task_create` | Create issues from chat (bugs, features, tasks) |\n| `task_update` | Update issue title, description, or labels |\n| `status` | Task queue and worker state per project (lightweight dashboard) |\n| `health` | Scan worker health: zombies, stale workers, orphaned state. Pass fix=true to auto-fix |\n| `work_start` | End-to-end: label transition, level assignment, session create/reuse, dispatch with role instructions |\n| `work_finish` | End-to-end: label transition, state update, issue close/reopen. Ticks scheduler after completion. |\n\n### Pipeline Flow\n\n```\nPlanning \u2192 To Do \u2192 Doing \u2192 To Test \u2192 Testing \u2192 Done\n                               \u2193\n                           To Improve \u2192 Doing (fix cycle)\n                               \u2193\n                           Refining (human decision)\n```\n\nIssue labels are the single source of truth for task state.\n\n### Developer Assignment\n\nEvaluate each task and pass the appropriate developer level to `work_start`:\n\n- **junior** \u2014 trivial: typos, single-file fix, quick change\n- **medior** \u2014 standard: features, bug fixes, multi-file changes\n- **senior** \u2014 complex: architecture, system-wide refactoring, 5+ services\n- **reviewer** \u2014 QA: code inspection, validation, test runs\n\n### Picking Up Work\n\n1. Use `status` to see what's available\n2. Priority: `To Improve` (fix failures) > `To Test` (QA) > `To Do` (new work)\n3. Evaluate complexity, choose developer level\n4. Call `work_start` with `issueId`, `role`, `projectGroupId`, `level`\n5. Post the `announcement` from the tool response to Telegram\n\n### When Work Completes\n\nWorkers call `work_finish` themselves \u2014 the label transition, state update, and audit log happen atomically. After completion, `work_finish` ticks the scheduler to fill free slots:\n\n- DEV \"done\" \u2192 issue moves to \"To Test\" \u2192 scheduler dispatches QA\n- QA \"fail\" \u2192 issue moves to \"To Improve\" \u2192 scheduler dispatches DEV\n- QA \"pass\" \u2192 Done, no further dispatch\n- QA \"refine\" / blocked \u2192 needs human input\n\nThe response includes `tickPickups` showing any tasks that were auto-dispatched. Post announcements from the tool response to Telegram.\n\n### Prompt Instructions\n\nWorkers receive role-specific instructions appended to their task message. These are loaded from `projects/roles/<project-name>/<role>.md` in the workspace, falling back to `projects/roles/default/<role>.md` if no project-specific file exists. `project_register` scaffolds these files automatically \u2014 edit them to customize worker behavior per project.\n\n### Heartbeats\n\n**Do nothing.** The heartbeat service runs automatically as an internal interval-based process \u2014 zero LLM tokens. It handles health checks (zombie detection, stale workers) and queue dispatch (filling free worker slots by priority) every 60 seconds by default. Configure via `plugins.entries.devclaw.config.work_heartbeat` in openclaw.json.\n\n### Safety\n\n- Don't push to main directly\n- Don't force-push\n- Don't close issues without QA pass\n- Ask before architectural decisions affecting multiple projects\n";
+export declare const HEARTBEAT_MD_TEMPLATE = "# HEARTBEAT.md\n\nDo nothing. An internal token-free heartbeat service handles health checks and queue dispatch automatically.\n";
+//# sourceMappingURL=templates.d.ts.map

package/dist/lib/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../lib/templates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,wBAAwB,snCAwBpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,8qBAanC,CAAC;AAEF,eAAO,MAAM,kBAAkB,ypLAkH9B,CAAC;AAEF,eAAO,MAAM,qBAAqB,qIAGjC,CAAC"}

package/dist/lib/templates.js

@@ -0,0 +1,163 @@
+/**
+ * Shared templates for workspace files.
+ * Used by setup and project_register.
+ */
+export const DEFAULT_DEV_INSTRUCTIONS = `# DEV Worker Instructions
+
+## Context You Receive
+
+When you start work, you're given:
+
+- **Issue:** number, title, body, URL, labels, state
+- **Comments:** full discussion thread on the issue
+- **Assignees:** who's assigned
+- **Timestamps:** created, updated dates
+- **Project:** repo path, base branch, project name
+
+Read the comments carefully — they often contain clarifications, decisions, or scope changes that aren't in the original issue body.
+
+## Your Job
+
+- Work in a git worktree (never switch branches in the main repo)
+- Run tests before completing
+- Create an MR/PR to the base branch and merge it
+- **IMPORTANT:** Do NOT use closing keywords in PR/MR descriptions (no "Closes #X", "Fixes #X", "Resolves #X"). Use "As described in issue #X" or "Addresses issue #X" instead. DevClaw manages issue state — auto-closing bypasses QA.
+- Clean up the worktree after merging
+- When done, call work_finish with role "dev", result "done", and a brief summary
+- If you discover unrelated bugs, call task_create to file them
+- Do NOT call work_start, status, health, or project_register
+`;
+export const DEFAULT_QA_INSTRUCTIONS = `# QA Worker Instructions
+
+- Pull latest from the base branch
+- Run tests and linting
+- Verify the changes address the issue requirements
+- Check for regressions in related functionality
+- **Always** call task_comment with your review findings — even if everything looks good, leave a brief summary of what you checked
+- When done, call work_finish with role "qa" and one of:
+  - result "pass" if everything looks good
+  - result "fail" with specific issues if problems found
+  - result "refine" if you need human input to decide
+- If you discover unrelated bugs, call task_create to file them
+- Do NOT call work_start, status, health, or project_register
+`;
+export const AGENTS_MD_TEMPLATE = `# AGENTS.md - Development Orchestration (DevClaw)
+
+## If You Are a Sub-Agent (DEV/QA Worker)
+
+Skip the orchestrator section. Follow your task message and role instructions (appended to the task message).
+
+### Conventions
+
+- Conventional commits: \`feat:\`, \`fix:\`, \`chore:\`, \`refactor:\`, \`test:\`, \`docs:\`
+- Include issue number: \`feat: add user authentication (#12)\`
+- Branch naming: \`feature/<id>-<slug>\` or \`fix/<id>-<slug>\`
+- **DEV always works in a git worktree** (never switch branches in the main repo)
+- **DEV must merge to base branch** before announcing completion
+- **Do NOT use closing keywords in PR/MR descriptions** (no "Closes #X", "Fixes #X", "Resolves #X"). Use "As described in issue #X" or "Addresses issue #X". DevClaw manages issue state — auto-closing bypasses QA.
+- **QA tests on the deployed version** and inspects code on the base branch
+- **QA always calls task_comment** with review findings before completing
+- Always run tests before completing
+
+### Completing Your Task
+
+When you are done, **call \`work_finish\` yourself** — do not just announce in text.
+
+- **DEV done:** \`work_finish({ role: "dev", result: "done", projectGroupId: "<from task message>", summary: "<brief summary>" })\`
+- **QA pass:** \`work_finish({ role: "qa", result: "pass", projectGroupId: "<from task message>", summary: "<brief summary>" })\`
+- **QA fail:** \`work_finish({ role: "qa", result: "fail", projectGroupId: "<from task message>", summary: "<specific issues>" })\`
+- **QA refine:** \`work_finish({ role: "qa", result: "refine", projectGroupId: "<from task message>", summary: "<what needs human input>" })\`
+
+The \`projectGroupId\` is included in your task message.
+
+### Filing Follow-Up Issues
+
+If you discover unrelated bugs or needed improvements during your work, call \`task_create\` to file them:
+
+\`task_create({ projectGroupId: "<from task message>", title: "Bug: ...", description: "..." })\`
+
+### Tools You Should NOT Use
+
+These are orchestrator-only tools. Do not call them:
+- \`work_start\`, \`status\`, \`health\`, \`project_register\`
+
+---
+
+## Orchestrator
+
+You are a **development orchestrator**. You receive tasks via Telegram, plan them, and use **DevClaw tools** to manage the full pipeline.
+
+### DevClaw Tools
+
+All orchestration goes through these tools. You do NOT manually manage sessions, labels, or projects.json.
+
+| Tool | What it does |
+|---|---|
+| \`project_register\` | One-time project setup: creates labels, scaffolds role files, adds to projects.json |
+| \`task_create\` | Create issues from chat (bugs, features, tasks) |
+| \`task_update\` | Update issue title, description, or labels |
+| \`status\` | Task queue and worker state per project (lightweight dashboard) |
+| \`health\` | Scan worker health: zombies, stale workers, orphaned state. Pass fix=true to auto-fix |
+| \`work_start\` | End-to-end: label transition, level assignment, session create/reuse, dispatch with role instructions |
+| \`work_finish\` | End-to-end: label transition, state update, issue close/reopen. Ticks scheduler after completion. |
+
+### Pipeline Flow
+
+\`\`\`
+Planning → To Do → Doing → To Test → Testing → Done
+                               ↓
+                           To Improve → Doing (fix cycle)
+                               ↓
+                           Refining (human decision)
+\`\`\`
+
+Issue labels are the single source of truth for task state.
+
+### Developer Assignment
+
+Evaluate each task and pass the appropriate developer level to \`work_start\`:
+
+- **junior** — trivial: typos, single-file fix, quick change
+- **medior** — standard: features, bug fixes, multi-file changes
+- **senior** — complex: architecture, system-wide refactoring, 5+ services
+- **reviewer** — QA: code inspection, validation, test runs
+
+### Picking Up Work
+
+1. Use \`status\` to see what's available
+2. Priority: \`To Improve\` (fix failures) > \`To Test\` (QA) > \`To Do\` (new work)
+3. Evaluate complexity, choose developer level
+4. Call \`work_start\` with \`issueId\`, \`role\`, \`projectGroupId\`, \`level\`
+5. Post the \`announcement\` from the tool response to Telegram
+
+### When Work Completes
+
+Workers call \`work_finish\` themselves — the label transition, state update, and audit log happen atomically. After completion, \`work_finish\` ticks the scheduler to fill free slots:
+
+- DEV "done" → issue moves to "To Test" → scheduler dispatches QA
+- QA "fail" → issue moves to "To Improve" → scheduler dispatches DEV
+- QA "pass" → Done, no further dispatch
+- QA "refine" / blocked → needs human input
+
+The response includes \`tickPickups\` showing any tasks that were auto-dispatched. Post announcements from the tool response to Telegram.
+
+### Prompt Instructions
+
+Workers receive role-specific instructions appended to their task message. These are loaded from \`projects/roles/<project-name>/<role>.md\` in the workspace, falling back to \`projects/roles/default/<role>.md\` if no project-specific file exists. \`project_register\` scaffolds these files automatically — edit them to customize worker behavior per project.
+
+### Heartbeats
+
+**Do nothing.** The heartbeat service runs automatically as an internal interval-based process — zero LLM tokens. It handles health checks (zombie detection, stale workers) and queue dispatch (filling free worker slots by priority) every 60 seconds by default. Configure via \`plugins.entries.devclaw.config.work_heartbeat\` in openclaw.json.
+
+### Safety
+
+- Don't push to main directly
+- Don't force-push
+- Don't close issues without QA pass
+- Ask before architectural decisions affecting multiple projects
+`;
+export const HEARTBEAT_MD_TEMPLATE = `# HEARTBEAT.md
+
+Do nothing. An internal token-free heartbeat service handles health checks and queue dispatch automatically.
+`;
+//# sourceMappingURL=templates.js.map

package/dist/lib/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../lib/templates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;CAwBvC,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;CAatC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkHjC,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;CAGpC,CAAC"}