@voidlabs.gg/voidshift-agents 0.4.4 → 0.4.5

package/README.md

@@ -86,8 +86,33 @@ vsf agents workflow add|edit|show|rename|move|rm
 vsf agents projects | project add|edit|show|rename|rm
 vsf agents homes | link DIR        # where the agents are installed
 vsf agents clean                   # old worktrees and run logs
+vsf agents validate [DIR]          # check the config and agent folders
 ```
 
+A workflow can also be a folder you write by hand,
+`~/.config/voidshift/agents/defs/NAME/agent.json`, with its prompt files next to
+it. Steps are the built-in ids above or your own:
+
+```json
+{
+  "triggers": [{ "source": "cron", "schedule": "0 7 * * 1-5", "task": "Morning brief" }],
+  "steps": [{ "id": "brief", "prompt": "brief.md", "output": "none", "model": "haiku", "timeoutMinutes": 10 }],
+  "maxRounds": 1,
+  "project": "tether-relay",
+  "writeBack": { "labels": true, "state": null, "comment": true }
+}
+```
+
+A step's `output` is `plan`, `verdict`, `commits`, `publish` or `none`; a failed
+`verdict` sends the work back to the nearest `plan` or `commits` step. `engine`,
+`model` and `timeoutMinutes` fall back to the config, and `write` to true only
+for `commits`. A `publish` step takes no prompt; the others take one `prompt`
+file or `skill`, which must ask for a `RESULT:` line (`plan`, `commits`) or a
+`VERDICT:` line (`verdict`). `writeBack` applies to card runs: `state` moves a
+verified card there (`null` never moves it), `labels: false` only takes the
+trigger label off, and `comment: false` skips the closing comment. Edit the file,
+then `vsf agents validate`.
+
 ### memory
 
 A folder of markdown notes, one topic per note, with an `INDEX.md` holding one
@@ -108,6 +133,20 @@ vsf memory on | off        # turn recall on or off
 Setup creates a vault at `~/memory` or uses one you already have. Codex asks you
 to trust the recall hook once: run `/hooks` in Codex.
 
+### Your profile
+
+Every agent run carries your profile, on any machine, without touching your
+Claude or Codex folder. `vsf agents profile init` creates
+`~/.config/voidshift/agents/profile/`:
+
+- `RULES.md` is added to every step's prompt (style, commit rules, tone).
+- `claude-settings.json` is passed to Claude runs with `--settings`, so hooks
+  come along. `{{profile}}` stands for the folder, so hook scripts can live in it.
+
+Setup also asks what the runner does to agent commits before it pushes them:
+remove AI co-author lines, and add `Signed-off-by` for repos that ask for a
+DCO. Only the new commits of that step are rewritten, never pushed ones.
+
 ## What to know
 
 - **Your own logins.** Agents run the official `claude` and `codex` CLIs you

package/dist/config.d.ts

@@ -1,12 +1,33 @@
 import type { Engine } from './engine.ts';
 export type StepId = 'vs-plan' | 'vs-plan-review' | 'vs-publish' | 'vs-dev' | 'vs-qa';
-export type Output = 'plan' | 'verdict' | 'commits' | 'publish';
+export type Output = 'plan' | 'verdict' | 'commits' | 'publish' | 'none';
+export declare const OUTPUTS: Output[];
 export declare const STEPS: Record<StepId, {
     label: string;
     output: Output;
     hint: string;
+    write: boolean;
+    role: 'dev' | 'review';
 }>;
-export declare const isProducer: (s: StepId) => boolean;
+export interface StepDef {
+    id: string;
+    label?: string;
+    skill?: string;
+    prompt?: string;
+    output: Output;
+    engine?: Engine;
+    model?: string;
+    timeoutMinutes?: number;
+    write?: boolean;
+}
+export type Step = StepId | StepDef;
+export declare const STEP_ID: RegExp;
+export declare const isBuiltin: (id: string) => id is StepId;
+export declare const outputOf: (s: Step) => Output;
+export declare const stepId: (s: Step) => string;
+export declare const stepLabel: (s: Step) => string;
+export declare const stepIdLabel: (id: string) => string;
+export declare const isProducer: (s: Step) => boolean;
 export declare const AGENTS: Record<string, {
     label: string;
     hint: string;
@@ -32,11 +53,17 @@ export interface Project {
     path: string;
     base?: string;
 }
+export interface WriteBack {
+    labels?: boolean;
+    state?: string | null;
+    comment?: boolean;
+}
 export interface Workflow {
     triggers: Trigger[];
-    steps: StepId[];
+    steps: Step[];
     maxRounds: number;
     project: string;
+    writeBack?: WriteBack;
 }
 export interface AgentsConfig {
     engine: Engine;
@@ -53,6 +80,11 @@ export interface AgentsConfig {
         dir: string;
     }[];
     enabled: string[];
+    commits?: {
+        signOff?: boolean;
+        dropAiTrailers?: boolean;
+    };
+    folders?: Record<string, string>;
 }
 export declare const TEMPLATES: Record<string, {
     steps: StepId[];
@@ -62,9 +94,26 @@ export declare const DEFAULTS: AgentsConfig;
 export declare const agentsDir: (configDir: string) => string;
 export declare const hasWork: (workflow: Pick<Workflow, "steps">) => boolean;
 export declare const hasProducer: (workflow: Pick<Workflow, "steps">) => boolean;
-export declare const describeSteps: (steps: StepId[]) => string;
+export declare const describeSteps: (steps: Step[]) => string;
 export declare const describeTriggers: (triggers: Trigger[]) => string;
 export declare const describeWorkflow: (c: Workflow) => string;
 export declare function migrate(saved: Record<string, any>): Partial<AgentsConfig>;
+export declare const defsDir: (configDir: string) => string;
+export declare const AGENT_FILE = "agent.json";
+export declare function agentFolders(configDir: string): string[];
+export declare function readAgentFolder(dir: string): Workflow;
 export declare function readAgentsConfig(configDir: string): AgentsConfig;
 export declare function writeAgentsConfig(configDir: string, config: AgentsConfig): void;
+export interface ResolvedStep {
+    id: string;
+    label: string;
+    output: Output;
+    engine: Engine;
+    model?: string;
+    timeoutMs: number;
+    write: boolean;
+    prompt: () => string;
+    builtin?: StepId;
+}
+export declare function stepFile(step: StepDef, dir?: string): string | null;
+export declare function resolveStep(step: Step, config: Pick<AgentsConfig, 'engine' | 'models' | 'timeoutMinutes'>, dir?: string): ResolvedStep;

package/dist/config.js

@@ -1,14 +1,25 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const OUTPUTS = ['plan', 'verdict', 'commits', 'publish', 'none'];
+// The built-in steps, the vs-* template. `write` is whether the agent may
+// edit files; `role` picks the model from config.models.
 export const STEPS = {
-    'vs-plan': { label: 'Plan', output: 'plan', hint: 'writes a plan and posts it to the card' },
-    'vs-plan-review': { label: 'Plan review', output: 'verdict', hint: 'checks the plan; on FIX the workflow goes back to Plan' },
-    'vs-publish': { label: 'Publish', output: 'publish', hint: 'creates and pushes the branch for the card' },
-    'vs-dev': { label: 'Dev', output: 'commits', hint: 'implements the plan, commits, opens a draft PR' },
-    'vs-qa': { label: 'QA', output: 'verdict', hint: 'CI, then code review, then a usability check; on FIX back to Dev' },
+    'vs-plan': { label: 'Plan', output: 'plan', hint: 'writes a plan and posts it to the card', write: false, role: 'dev' },
+    'vs-plan-review': { label: 'Plan review', output: 'verdict', hint: 'checks the plan; on FIX the workflow goes back to Plan', write: false, role: 'review' },
+    'vs-publish': { label: 'Publish', output: 'publish', hint: 'creates and pushes the branch for the card', write: false, role: 'dev' },
+    'vs-dev': { label: 'Dev', output: 'commits', hint: 'implements the plan, commits, opens a draft PR', write: true, role: 'dev' },
+    'vs-qa': { label: 'QA', output: 'verdict', hint: 'CI, then code review, then a usability check; on FIX back to Dev', write: true, role: 'review' },
 };
+// What a custom step id may look like.
+export const STEP_ID = /^[a-z0-9][a-z0-9-]*$/;
+export const isBuiltin = (id) => Object.hasOwn(STEPS, id);
+export const outputOf = (s) => (typeof s === 'string' ? STEPS[s].output : s.output);
+export const stepId = (s) => (typeof s === 'string' ? s : s.id);
+export const stepLabel = (s) => (typeof s === 'string' ? STEPS[s]?.label ?? s : s.label ?? s.id);
+export const stepIdLabel = (id) => (isBuiltin(id) ? STEPS[id].label : id);
 // Steps a failed verdict can send work back to.
-export const isProducer = (s) => STEPS[s].output === 'plan' || STEPS[s].output === 'commits';
+export const isProducer = (s) => outputOf(s) === 'plan' || outputOf(s) === 'commits';
 // The agents in the pack, as setup describes them.
 export const AGENTS = {
     'vs-plan': { label: 'Plan', hint: 'plans a card against the code' },
@@ -50,9 +61,9 @@ export const DEFAULTS = {
 };
 export const agentsDir = (configDir) => join(configDir, 'agents');
 const configPath = (configDir) => join(agentsDir(configDir), 'config.json');
-export const hasWork = (workflow) => workflow.steps.some((s) => STEPS[s].output === 'commits');
+export const hasWork = (workflow) => workflow.steps.some((s) => outputOf(s) === 'commits');
 export const hasProducer = (workflow) => workflow.steps.some(isProducer);
-export const describeSteps = (steps) => steps.map((s) => STEPS[s].label).join(' → ');
+export const describeSteps = (steps) => steps.map(stepLabel).join(' → ');
 export const describeTriggers = (triggers) => triggers.map(describeTrigger).join(', ');
 export const describeWorkflow = (c) => `when ${describeTriggers(c.triggers)}: ${describeSteps(c.steps)} in ${c.project}`;
 // Step ids that were folded into QA.
@@ -98,14 +109,88 @@ export function migrate(saved) {
     const enabled = [...new Set((saved.enabled ?? []).map((a) => (a in RENAMED ? RENAMED[a] : a)).filter(Boolean))];
     return { ...rest, ...(models ? { models } : {}), projects, workflows, enabled };
 }
+// Agent folders: defs/<name>/agent.json, with its prompt files next to it.
+export const defsDir = (configDir) => join(agentsDir(configDir), 'defs');
+export const AGENT_FILE = 'agent.json';
+export function agentFolders(configDir) {
+    try {
+        return readdirSync(defsDir(configDir), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => join(defsDir(configDir), e.name));
+    }
+    catch {
+        return [];
+    }
+}
+// The workflow in an agent folder. Throws when agent.json is missing or not JSON.
+export function readAgentFolder(dir) {
+    const value = JSON.parse(readFileSync(join(dir, AGENT_FILE), 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${AGENT_FILE} must be an object`);
+    const { triggers, steps, maxRounds, project, writeBack } = value;
+    return { triggers, steps, maxRounds, project, ...(writeBack !== undefined ? { writeBack } : {}) };
+}
 export function readAgentsConfig(configDir) {
     const path = configPath(configDir);
-    if (!existsSync(path))
-        return structuredClone(DEFAULTS);
-    const saved = migrate(JSON.parse(readFileSync(path, 'utf8')));
-    return { ...structuredClone(DEFAULTS), ...saved, models: { ...DEFAULTS.models, ...saved.models } };
+    let config = structuredClone(DEFAULTS);
+    if (existsSync(path)) {
+        const saved = migrate(JSON.parse(readFileSync(path, 'utf8')));
+        config = { ...config, ...saved, models: { ...DEFAULTS.models, ...saved.models } };
+    }
+    // A name config.json already uses wins, and a broken folder is skipped:
+    // `vsf agents validate` reports both.
+    for (const dir of agentFolders(configDir)) {
+        const name = basename(dir);
+        if (config.workflows[name])
+            continue;
+        try {
+            config.workflows[name] = readAgentFolder(dir);
+            config.folders = { ...config.folders, [name]: dir };
+        }
+        catch {
+            // skipped
+        }
+    }
+    return config;
 }
 export function writeAgentsConfig(configDir, config) {
     mkdirSync(agentsDir(configDir), { recursive: true });
-    writeFileSync(configPath(configDir), JSON.stringify(config, null, 2) + '\n');
+    const { folders, ...rest } = config;
+    const workflows = Object.fromEntries(Object.entries(config.workflows).filter(([name]) => !folders?.[name]));
+    writeFileSync(configPath(configDir), JSON.stringify({ ...rest, workflows }, null, 2) + '\n');
+}
+const packDir = fileURLToPath(new URL('../pack/', import.meta.url));
+const packSkill = (name) => join(packDir, name, 'SKILL.md');
+// The file a custom step's prompt comes from: its prompt file, a pack skill,
+// or a skill folder next to agent.json. Null for a step with neither.
+export function stepFile(step, dir = '.') {
+    if (step.prompt)
+        return resolve(dir, step.prompt);
+    if (!step.skill)
+        return null;
+    if (STEP_ID.test(step.skill) && existsSync(packSkill(step.skill)))
+        return packSkill(step.skill);
+    return resolve(dir, step.skill, 'SKILL.md');
+}
+export function resolveStep(step, config, dir) {
+    if (typeof step === 'string') {
+        const s = STEPS[step];
+        return {
+            id: step, label: s.label, output: s.output, engine: config.engine, model: config.models[s.role],
+            timeoutMs: config.timeoutMinutes * 60_000, write: s.write, prompt: () => readFileSync(packSkill(step), 'utf8'), builtin: step,
+        };
+    }
+    return {
+        id: step.id,
+        label: step.label ?? step.id,
+        output: step.output,
+        engine: step.engine ?? config.engine,
+        model: step.model ?? config.models[step.output === 'verdict' ? 'review' : 'dev'],
+        timeoutMs: (step.timeoutMinutes ?? config.timeoutMinutes) * 60_000,
+        write: step.write ?? step.output === 'commits',
+        prompt: () => {
+            const file = stepFile(step, dir);
+            if (!file)
+                throw new Error(`Step ${step.id} has no prompt or skill.`);
+            return readFileSync(file, 'utf8');
+        },
+    };
 }

package/dist/control.js

@@ -6,7 +6,7 @@ import { agentsDir, isCardTrigger, readAgentsConfig } from "./config.js";
 import { isPaused, listRuns, ours, clearCurrent, liveCurrent, readCurrent, setPaused, writeRun } from "./state.js";
 import { runnerService } from "./service.js";
 import { TRACKERS, trackersFor } from "./tracker.js";
-import { parseStep, resolveName, stepNames } from "./names.js";
+import { parseFrom, resolveName, stepNames } from "./names.js";
 import { isStatusLabel } from "./workflow.js";
 import { cancelCard, tick } from "./runner.js";
 const HOUR = 3_600_000;
@@ -373,7 +373,7 @@ const run = guard(async (args, ctx) => {
     }
     let from;
     if (p.values.from) {
-        from = parseStep(p.values.from);
+        from = parseFrom(p.values.from);
         if (!from) {
             ctx.log(`Unknown step ${p.values.from}. Steps: ${stepNames()}.`);
             return 2;

package/dist/engine.d.ts

@@ -9,6 +9,7 @@ export interface RunOptions {
     logFile: string;
     timeoutMs?: number;
     vault?: string;
+    settingsFile?: string;
 }
 export declare function engineArgs(o: RunOptions, outFile: string): {
     cmd: string;

package/dist/engine.js

@@ -17,6 +17,8 @@ export function engineArgs(o, outFile) {
             args.push('--permission-mode', 'acceptEdits');
         if (o.model)
             args.push('--model', o.model);
+        if (o.settingsFile)
+            args.push('--settings', o.settingsFile);
         return { cmd: 'claude', args };
     }
     const args = ['exec', '-C', o.cwd, '-s', o.write ? 'workspace-write' : 'read-only', '-o', outFile];

package/dist/git.d.ts

@@ -28,3 +28,9 @@ export declare function waitForChecks(worktree: string, branch: string, timeoutM
     report: string;
 }>;
 export declare function resetWorktree(worktree: string): void;
+export interface CommitPolicy {
+    signOff?: boolean;
+    dropAiTrailers?: boolean;
+}
+export declare function applyPolicy(message: string, policy: CommitPolicy, signer: string | null, cwd: string): string;
+export declare function enforceCommitPolicy(worktree: string, from: string, policy: CommitPolicy): number;

package/dist/git.js

@@ -134,3 +134,63 @@ export function resetWorktree(worktree) {
     sh('git', ['reset', '--hard', 'HEAD'], worktree);
     sh('git', ['clean', '-fd'], worktree);
 }
+const AI_LINE = /^(co-authored-by:.*(claude|anthropic|codex|openai|copilot|gemini|cursor)|.*generated with \[?(claude|codex)).*$/i;
+// The message with AI lines removed and a sign-off added, as the policy asks.
+export function applyPolicy(message, policy, signer, cwd) {
+    let msg = message.replace(/\r\n/g, '\n');
+    if (policy.dropAiTrailers)
+        msg = msg.split('\n').filter((l) => !AI_LINE.test(l.trim())).join('\n');
+    msg = msg.replace(/\s+$/, '') + '\n';
+    if (policy.signOff && signer) {
+        // git's own trailer rules decide the blank line and skip a duplicate.
+        const r = spawnSync('git', ['interpret-trailers', '--if-exists', 'addIfDifferent', '--trailer', `Signed-off-by: ${signer}`], { cwd, input: msg, encoding: 'utf8' });
+        if (r.status === 0)
+            msg = r.stdout;
+    }
+    return msg;
+}
+// Rewrites the commits after `from` up to HEAD so their messages follow the
+// policy. Trees, authors and dates stay as they were; only commits not yet
+// pushed may be passed. Returns how many changed.
+export function enforceCommitPolicy(worktree, from, policy) {
+    if (!policy.signOff && !policy.dropAiTrailers)
+        return 0;
+    const name = sh('git', ['config', 'user.name'], worktree).stdout;
+    const email = sh('git', ['config', 'user.email'], worktree).stdout;
+    const signer = name && email ? `${name} <${email}>` : null;
+    const list = sh('git', ['rev-list', '--reverse', '--parents', `${from}..HEAD`], worktree);
+    if (!list.ok || !list.stdout)
+        return 0;
+    const map = new Map();
+    let changed = 0;
+    let head = '';
+    for (const line of list.stdout.split('\n')) {
+        const [sha, ...parents] = line.split(' ');
+        const info = must(sh('git', ['log', '-1', '--format=%T%x00%an%x00%ae%x00%aD%x00%cn%x00%ce%x00%cD', sha], worktree), 'git log');
+        const [tree, an, ae, ad, cn, ce, cd] = info.split('\0');
+        const raw = spawnSync('git', ['log', '-1', '--format=%B', sha], { cwd: worktree, encoding: 'utf8' }).stdout ?? '';
+        const message = applyPolicy(raw, policy, signer, worktree);
+        const newParents = parents.map((p) => map.get(p) ?? p);
+        if (message === raw.replace(/\s+$/, '') + '\n' && newParents.every((p, i) => p === parents[i])) {
+            map.set(sha, sha);
+            head = sha;
+            continue;
+        }
+        const r = spawnSync('git', ['commit-tree', tree, ...newParents.flatMap((p) => ['-p', p]), '-F', '-'], {
+            cwd: worktree,
+            input: message,
+            encoding: 'utf8',
+            env: { ...process.env, GIT_AUTHOR_NAME: an, GIT_AUTHOR_EMAIL: ae, GIT_AUTHOR_DATE: ad, GIT_COMMITTER_NAME: cn, GIT_COMMITTER_EMAIL: ce, GIT_COMMITTER_DATE: cd },
+        });
+        if (r.status !== 0)
+            throw new Error(`git commit-tree failed: ${r.stderr}`);
+        const next = r.stdout.trim();
+        map.set(sha, next);
+        head = next;
+        changed++;
+    }
+    // Same tree at the tip, so moving the branch leaves the files untouched.
+    if (changed)
+        must(sh('git', ['reset', '-q', '--soft', head], worktree), 'git reset');
+    return changed;
+}

package/dist/index.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
-import { AGENTS, STEPS, TEMPLATES, isProducer, agentsDir, describeSteps, describeTrigger, describeTriggers, describeWorkflow, stepEnabled, visibleAgents, readAgentsConfig, writeAgentsConfig, DEFAULTS } from "./config.js";
+import { AGENTS, AGENT_FILE, STEPS, TEMPLATES, isProducer, agentFolders, agentsDir, describeSteps, describeTrigger, describeTriggers, describeWorkflow, stepEnabled, stepId, visibleAgents, readAgentsConfig, writeAgentsConfig, DEFAULTS } from "./config.js";
 import { controlChecks, controlCommands, controlUsage } from "./control.js";
 import { keyStore, looksLikeLinearKey, readLinearKey, readSecret, storeLinearKey, storeSecret } from "./secrets.js";
 import { TRACKERS } from "./tracker.js";
@@ -12,8 +12,9 @@ import { createVoidTrack } from "./voidtrack.js";
 import { parseCron } from "./cron.js";
 import { trackersInUse } from "./control.js";
 import { runnerService } from "./service.js";
+import { initProfile, profileChecks, profileDir, readRules, renderClaudeSettings, CLAUDE_SETTINGS, RULES_FILE } from "./profile.js";
 import { createLinear } from "./linear.js";
-import { TRIGGER_FORMS, duplicateTriggerWarnings, moveKey, parseTrigger, renameKey, sameTrigger, validateConfig, validateWorkflow, workflowsUsing } from "./manage.js";
+import { TRIGGER_FORMS, duplicateTriggerWarnings, moveKey, parseTrigger, renameKey, sameTrigger, validateAgentFolder, validateConfig, validateWorkflow, workflowsUsing } from "./manage.js";
 import { parseStep, resolveName, stepNames } from "./names.js";
 import { findRepos } from "./repos.js";
 import { defaultBranch, sh } from "./git.js";
@@ -374,6 +375,8 @@ const USAGE = [
     ['link DIR [--claude | --codex]', 'Link the agents into a config folder'],
     ['unlink DIR', 'Remove the agents from a config folder'],
     ['key [--voidtrack]', 'Store or replace the Linear or VoidTrack API key (reads stdin without a terminal)'],
+    ['profile [init]', `Your profile: rules (${RULES_FILE}) and Claude settings (${CLAUDE_SETTINGS}) every agent run carries; init creates it`],
+    ['validate [DIR]', `Check an agent folder (DIR/${AGENT_FILE} and its prompts), or the config and every folder under agents/defs`],
     ['help [COMMAND]', 'Show this list, or one command'],
 ];
 const usageOf = (name) => USAGE.filter(([c]) => c === name || c.startsWith(`${name} `))
@@ -504,6 +507,14 @@ function pickWorkflow(config, input, ctx) {
     }
     return r.name;
 }
+// A workflow from an agent folder is changed by editing its file. True (and
+// says so) when `name` is one.
+function inFolder(config, name, ctx) {
+    const dir = config.folders?.[name];
+    if (dir)
+        ctx.log(`${name} is defined in ${tilde(join(dir, AGENT_FILE))}; edit that file.`);
+    return !!dir;
+}
 async function teamsOrNull(ctx) {
     try {
         return await linear(ctx.configDir).teams();
@@ -628,6 +639,8 @@ const workflowSubs = {
         const name = pickWorkflow(config, p.positionals[0], ctx);
         if (!name)
             return 1;
+        if (inFolder(config, name, ctx))
+            return 1;
         const flags = readWorkflowFlags(p.values, config);
         if ('error' in flags) {
             ctx.log(flags.error);
@@ -688,6 +701,8 @@ const workflowSubs = {
         const old = pickWorkflow(config, p.positionals[0], ctx);
         if (!old)
             return 1;
+        if (inFolder(config, old, ctx))
+            return 1;
         const next = p.positionals[1].trim();
         if (!next) {
             ctx.log('The new name cannot be empty.');
@@ -712,6 +727,8 @@ const workflowSubs = {
         const name = pickWorkflow(config, p.positionals[0], ctx);
         if (!name)
             return 1;
+        if (inFolder(config, name, ctx))
+            return 1;
         const ok = await confirmed(`Delete workflow ${name}?`, !!p.values.yes, ctx);
         if (ok === 'refused')
             return 2;
@@ -740,6 +757,8 @@ const workflowSubs = {
         const name = pickWorkflow(config, p.positionals[0], ctx);
         if (!name)
             return 1;
+        if (inFolder(config, name, ctx))
+            return 1;
         let place;
         if (v.first)
             place = { first: true };
@@ -1062,6 +1081,11 @@ const agents = {
                 config.models = { ...DEFAULTS.models };
         }
         config.engine = engine;
+        // What the runner does to agent commits before pushing them.
+        const commits = config.commits ?? {};
+        commits.dropAiTrailers = await ui.confirm('Remove AI co-author lines from agent commits?', commits.dropAiTrailers ?? true);
+        commits.signOff = await ui.confirm('Sign off agent commits (Signed-off-by, for repos that ask for a DCO)?', commits.signOff ?? false);
+        config.commits = commits;
         const name = await currentLinearUser(ctx.configDir);
         if (!name || !(await ui.confirm(`Keep using Linear as ${name}?`))) {
             if (!(await setupKey(ui, ctx.configDir)))
@@ -1119,7 +1143,14 @@ const agents = {
             : broken.length
                 ? { name: 'agent workflows', status: 'fail', detail: `${broken.join(', ')} point at a missing project`, fix: 'vsf agents project edit' }
                 : { name: 'agent workflows', status: 'ok', detail: `${workflows.length} ready` });
-        return [...checks, ...(await controlChecks(ctx))];
+        const folders = agentFolders(ctx.configDir);
+        if (folders.length) {
+            const bad = folders.filter((d) => validateAgentFolder(d, saved).length).map((d) => basename(d));
+            checks.push(bad.length
+                ? { name: 'agent folders', status: 'fail', detail: `${bad.join(', ')} ${bad.length === 1 ? 'has' : 'have'} problems`, fix: 'vsf agents validate' }
+                : { name: 'agent folders', status: 'ok', detail: `${folders.length} valid` });
+        }
+        return [...checks, ...profileChecks(ctx.configDir), ...(await controlChecks(ctx))];
     },
     commands: {
         ...controlCommands,
@@ -1129,7 +1160,7 @@ const agents = {
                 return p;
             const config = readAgentsConfig(ctx.configDir);
             if (p.values.json)
-                out(ctx, Object.entries(config.workflows).map(([name, w]) => ({ name, ...w })));
+                out(ctx, Object.entries(config.workflows).map(([name, w]) => ({ name, ...w, steps: w.steps.map(stepId) })));
             else if (!Object.keys(config.workflows).length)
                 ctx.log('No workflows yet. vsf agents workflow add creates one.');
             else
@@ -1143,6 +1174,58 @@ const agents = {
             return 0;
         },
         workflow: (args, ctx) => group('workflow', workflowSubs, args, ctx),
+        async profile(args, ctx) {
+            const p = begin('profile', args, {}, ctx);
+            if (typeof p === 'number')
+                return p;
+            const dir = profileDir(ctx.configDir);
+            if (p.positionals[0] === 'init') {
+                const made = initProfile(ctx.configDir);
+                ctx.log(made.length ? `Created ${made.join(', ')} in ${tilde(dir)}.` : `${tilde(dir)} already exists; nothing changed.`);
+                return 0;
+            }
+            if (p.positionals.length) {
+                ctx.log(usageOf('profile'));
+                return 2;
+            }
+            ctx.log(`Profile: ${tilde(dir)}${existsSync(dir) ? '' : ' (not created yet: vsf agents profile init)'}`);
+            const rules = readRules(ctx.configDir).replace(/<!--[\s\S]*?-->/g, '').trim();
+            ctx.log(`Rules: ${rules ? `${rules.split('\n').length} lines in ${RULES_FILE}, added to every step's prompt` : 'none'}`);
+            let settings = 'none';
+            try {
+                settings = renderClaudeSettings(ctx.configDir) === null ? 'none' : `${CLAUDE_SETTINGS}, passed to every Claude run`;
+            }
+            catch (err) {
+                settings = `broken: ${err.message}`;
+            }
+            ctx.log(`Claude settings: ${settings}`);
+            const c = readAgentsConfig(ctx.configDir).commits ?? {};
+            ctx.log(`Commits: ${[c.dropAiTrailers ? 'AI co-author lines removed' : 'AI lines kept', c.signOff ? 'signed off' : 'not signed off'].join(', ')} (commits in the agents config)`);
+            return 0;
+        },
+        async validate(args, ctx) {
+            const p = begin('validate', args, {}, ctx);
+            if (typeof p === 'number')
+                return p;
+            if (p.positionals.length > 1) {
+                ctx.log('Give one folder at most.');
+                ctx.log(usageOf('validate'));
+                return 2;
+            }
+            const config = readAgentsConfig(ctx.configDir);
+            const problems = [];
+            const dirs = p.positionals.length ? [resolve(expandHome(p.positionals[0]))] : agentFolders(ctx.configDir);
+            if (!p.positionals.length)
+                problems.push(...validateConfig(config));
+            for (const dir of dirs)
+                for (const line of validateAgentFolder(dir, config))
+                    problems.push(`${basename(dir)}: ${line}`);
+            for (const line of problems)
+                ctx.log(line);
+            if (!problems.length)
+                ctx.log(p.positionals.length ? `${basename(dirs[0])} is valid.` : `Config and ${plural(dirs.length, 'agent folder')} are valid.`);
+            return problems.length ? 1 : 0;
+        },
         async projects(args, ctx) {
             const p = begin('projects', args, { json: { type: 'boolean' } }, ctx);
             if (typeof p === 'number')

package/dist/manage.d.ts

@@ -1,5 +1,7 @@
-import { type AgentsConfig, type Trigger, type Workflow } from './config.ts';
-export declare function validateWorkflow(config: Pick<AgentsConfig, 'enabled' | 'projects'>, workflow: Workflow): string[];
+import { type AgentsConfig, type Step, type Trigger, type Workflow } from './config.ts';
+export declare function validateStep(step: Step, config: Pick<AgentsConfig, 'enabled'>, dir?: string): string[];
+export declare function validateWorkflow(config: Pick<AgentsConfig, 'enabled' | 'projects'>, workflow: Workflow, dir?: string): string[];
+export declare function validateAgentFolder(dir: string, config: Pick<AgentsConfig, 'enabled' | 'projects' | 'workflows' | 'folders'>): string[];
 export declare const TRIGGER_FORMS = "TEAM:LABEL (Linear), voidtrack:TEAM:LABEL, or cron:SCHEDULE:TASK";
 export declare function parseTrigger(input: string): Trigger | null;
 export declare const sameTrigger: (a: Trigger, b: Trigger) => boolean;

package/dist/manage.js

@@ -1,10 +1,66 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { AGENTS, STEPS, describeTrigger, triggerSpec } from "./config.js";
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { AGENTS, AGENT_FILE, OUTPUTS, STEP_ID, isBuiltin, readAgentFolder, stepFile, describeTrigger, triggerSpec } from "./config.js";
 import { parseCron } from "./cron.js";
 const isInt = (v, min, max) => typeof v === 'number' && Number.isInteger(v) && v >= min && v <= max;
+// The line a step's prompt must ask for, so the runner can read the result.
+const RESULT_LINE = { plan: 'RESULT:', commits: 'RESULT:', verdict: 'VERDICT:' };
+// Everything wrong with one step. `dir` is the agent folder its files are in.
+export function validateStep(step, config, dir) {
+    if (typeof step === 'string') {
+        if (!isBuiltin(step))
+            return [`Unknown step ${step}.`];
+        return config.enabled.length && !config.enabled.includes(step) ? [`Step ${step} is not enabled.`] : [];
+    }
+    if (!isObj(step))
+        return ['A step must be a step id or an object.'];
+    const problems = [];
+    const id = typeof step.id === 'string' && STEP_ID.test(step.id) ? step.id : null;
+    if (!id)
+        problems.push(`Step id ${String(step.id)} must be lowercase letters, digits and dashes.`);
+    else if (isBuiltin(id))
+        problems.push(`Step id ${id} is a built-in step; use "${id}" on its own, or another id.`);
+    const name = id ?? 'A step';
+    if (!OUTPUTS.includes(step.output))
+        problems.push(`${name} output must be one of: ${OUTPUTS.join(', ')}.`);
+    if (step.label !== undefined && typeof step.label !== 'string')
+        problems.push(`${name} label must be text.`);
+    if (step.prompt !== undefined && typeof step.prompt !== 'string')
+        problems.push(`${name} prompt must be a file name.`);
+    if (step.skill !== undefined && typeof step.skill !== 'string')
+        problems.push(`${name} skill must be a name or a folder.`);
+    const sources = [step.skill, step.prompt].filter((v) => v !== undefined).length;
+    if (step.output === 'publish') {
+        if (sources)
+            problems.push(`${name} only pushes the branch, so it takes no skill or prompt.`);
+    }
+    else if (sources !== 1)
+        problems.push(`${name} needs exactly one of skill or prompt.`);
+    else if (typeof (step.prompt ?? step.skill) === 'string') {
+        const file = stepFile(step, dir);
+        if (!file || !existsSync(file))
+            problems.push(`${name} ${step.prompt ? 'prompt' : 'skill'} ${file ?? ''} does not exist.`);
+        else {
+            const want = RESULT_LINE[step.output];
+            if (want && !readFileSync(file, 'utf8').includes(want))
+                problems.push(`${name} prompt never asks for a ${want} line.`);
+        }
+    }
+    if (step.engine !== undefined && step.engine !== 'claude' && step.engine !== 'codex')
+        problems.push(`${name} engine must be claude or codex.`);
+    if (step.model !== undefined && typeof step.model !== 'string')
+        problems.push(`${name} model must be text.`);
+    if (step.timeoutMinutes !== undefined && !isInt(step.timeoutMinutes, 1, 480))
+        problems.push(`${name} timeoutMinutes must be a whole number from 1 to 480.`);
+    if (step.write !== undefined && typeof step.write !== 'boolean')
+        problems.push(`${name} write must be true or false.`);
+    else if (step.write === false && step.output === 'commits')
+        problems.push(`${name} makes commits, so write cannot be false.`);
+    return problems;
+}
 // Everything wrong with one workflow, in plain words. Empty means it is fine.
-export function validateWorkflow(config, workflow) {
+// `dir` is the agent folder a folder workflow comes from.
+export function validateWorkflow(config, workflow, dir) {
     const problems = [];
     if (!workflow.triggers?.length)
         problems.push('Needs at least one trigger.');
@@ -26,16 +82,50 @@ export function validateWorkflow(config, workflow) {
     }
     if (!workflow.steps?.length)
         problems.push('Needs at least one step.');
-    for (const s of workflow.steps ?? []) {
-        if (!(s in STEPS))
-            problems.push(`Unknown step ${s}.`);
-        else if (config.enabled.length && !config.enabled.includes(s))
-            problems.push(`Step ${s} is not enabled.`);
+    const ids = new Set();
+    for (const s of Array.isArray(workflow.steps) ? workflow.steps : []) {
+        problems.push(...validateStep(s, config, dir));
+        const id = typeof s === 'string' ? s : isObj(s) ? s.id : undefined;
+        if (typeof id === 'string' && !isBuiltin(id)) {
+            if (ids.has(id))
+                problems.push(`Step id ${id} is used twice.`);
+            ids.add(id);
+        }
     }
     if (!config.projects[workflow.project])
         problems.push(`Project ${workflow.project} does not exist.`);
     if (!isInt(workflow.maxRounds, 1, 9))
         problems.push('Rounds must be a whole number from 1 to 9.');
+    const wb = workflow.writeBack;
+    if (wb !== undefined) {
+        if (!isObj(wb))
+            problems.push('writeBack must be an object.');
+        else {
+            if (wb.labels !== undefined && typeof wb.labels !== 'boolean')
+                problems.push('writeBack.labels must be true or false.');
+            if (wb.comment !== undefined && typeof wb.comment !== 'boolean')
+                problems.push('writeBack.comment must be true or false.');
+            if (wb.state !== undefined && wb.state !== null && (typeof wb.state !== 'string' || !wb.state.trim()))
+                problems.push('writeBack.state must be a state name, or null to never move the card.');
+        }
+    }
+    return problems;
+}
+// Everything wrong with an agent folder: its agent.json, its workflow and
+// prompt files, and a name config.json already uses.
+export function validateAgentFolder(dir, config) {
+    let workflow;
+    try {
+        workflow = readAgentFolder(dir);
+    }
+    catch (err) {
+        return [`${AGENT_FILE}: ${err.message}`];
+    }
+    const problems = validateWorkflow(config, workflow, dir);
+    const name = basename(dir);
+    const from = config.folders?.[name];
+    if (config.workflows[name] && (!from || resolve(from) !== resolve(dir)))
+        problems.push(`config.json already has a workflow named ${name}, and it wins. Rename the folder.`);
     return problems;
 }
 export const TRIGGER_FORMS = 'TEAM:LABEL (Linear), voidtrack:TEAM:LABEL, or cron:SCHEDULE:TASK';
@@ -121,6 +211,8 @@ export function validateConfig(value, saved) {
     }
     if (!Array.isArray(value.enabled) || value.enabled.some((a) => typeof a !== 'string' || !(a in AGENTS)))
         problems.push(`enabled must list agents from: ${Object.keys(AGENTS).join(', ')}.`);
+    if (value.commits !== undefined && (!isObj(value.commits) || Object.entries(value.commits).some(([k, v]) => !['signOff', 'dropAiTrailers'].includes(k) || typeof v !== 'boolean')))
+        problems.push('commits may only set signOff and dropAiTrailers, each true or false.');
     if (!Array.isArray(value.homes) || value.homes.some((h) => !isObj(h) || (h.kind !== 'claude' && h.kind !== 'codex') || typeof h.dir !== 'string'))
         problems.push('homes must be a list of { kind: claude or codex, dir }.');
     if (!isObj(value.workflows))
@@ -128,6 +220,9 @@ export function validateConfig(value, saved) {
     else {
         const ctx = { enabled: Array.isArray(value.enabled) ? value.enabled : [], projects: (projects ?? {}) };
         for (const [name, w] of Object.entries(value.workflows)) {
+            // Folder workflows are checked with their folder, by vsf agents validate.
+            if (isObj(value.folders) && value.folders[name])
+                continue;
             if (!isObj(w))
                 problems.push(`Workflow ${name} must be an object.`);
             else {

package/dist/names.d.ts

@@ -5,4 +5,5 @@ export declare function resolveName(names: string[], input: string, kind: string
     error: string;
 };
 export declare function parseStep(input: string): StepId | null;
+export declare const parseFrom: (input: string) => string | null;
 export declare const stepNames: () => string;

package/dist/names.js

@@ -1,4 +1,4 @@
-import { STEPS } from "./config.js";
+import { STEPS, STEP_ID } from "./config.js";
 // A workflow or project named in a command: the exact name, or the start of
 // exactly one name, e.g. "tether" for tether-relay-build.
 export function resolveName(names, input, kind) {
@@ -23,4 +23,7 @@ export function parseStep(input) {
     }
     return null;
 }
+// A step for --from: a built-in step by any of its names, or any id a custom
+// step could have. Whether the workflow has it is checked once it is known.
+export const parseFrom = (input) => parseStep(input) ?? (STEP_ID.test(input) ? input : null);
 export const stepNames = () => Object.keys(STEPS).map((id) => id.replace(/^vs-/, '')).join(', ');

package/dist/profile.d.ts

@@ -0,0 +1,10 @@
+import type { Check } from './types.ts';
+export declare const profileDir: (configDir: string) => string;
+export declare const RULES_FILE = "RULES.md";
+export declare const CLAUDE_SETTINGS = "claude-settings.json";
+export declare function readRules(configDir: string): string;
+export declare function renderClaudeSettings(configDir: string): string | null;
+export declare function claudeSettingsFile(configDir: string, runDir: string): string | undefined;
+export declare const rulesSection: (rules: string) => string;
+export declare function initProfile(configDir: string): string[];
+export declare function profileChecks(configDir: string): Check[];

package/dist/profile.js

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentsDir } from "./config.js";
+// Your profile: what every agent run carries, on any machine, without touching
+// a Claude or Codex folder. RULES.md is added to every step's prompt, and
+// claude-settings.json is passed to Claude runs, with {{profile}} standing for
+// this folder so hooks can live in it.
+export const profileDir = (configDir) => join(agentsDir(configDir), 'profile');
+export const RULES_FILE = 'RULES.md';
+export const CLAUDE_SETTINGS = 'claude-settings.json';
+export function readRules(configDir) {
+    const path = join(profileDir(configDir), RULES_FILE);
+    return existsSync(path) ? readFileSync(path, 'utf8').trim() : '';
+}
+// The Claude settings with {{profile}} filled in, as text, or null when there
+// are none. Throws when the file is not a JSON object.
+export function renderClaudeSettings(configDir) {
+    const dir = profileDir(configDir);
+    const path = join(dir, CLAUDE_SETTINGS);
+    if (!existsSync(path))
+        return null;
+    const text = readFileSync(path, 'utf8').replaceAll('{{profile}}', dir);
+    const value = JSON.parse(text);
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${CLAUDE_SETTINGS} must be a JSON object`);
+    return text;
+}
+// Writes the rendered settings into a run folder and returns the path, or
+// undefined when the profile has none.
+export function claudeSettingsFile(configDir, runDir) {
+    const text = renderClaudeSettings(configDir);
+    if (text === null)
+        return undefined;
+    const out = join(runDir, CLAUDE_SETTINGS);
+    writeFileSync(out, text);
+    return out;
+}
+// The prompt section for your rules, empty when there are none.
+export const rulesSection = (rules) => (rules ? `# Your rules\n\nFollow these in everything you write, including commits and comments.\n\n${rules}` : '');
+const STARTER_RULES = `<!-- Rules every agent follows on every run, on every machine.
+     Write them as you would tell a teammate. Delete this comment. -->
+`;
+// Creates the folder with a starter RULES.md. Existing files are kept.
+export function initProfile(configDir) {
+    const dir = profileDir(configDir);
+    mkdirSync(dir, { recursive: true });
+    const made = [];
+    const rules = join(dir, RULES_FILE);
+    if (!existsSync(rules)) {
+        writeFileSync(rules, STARTER_RULES);
+        made.push(RULES_FILE);
+    }
+    return made;
+}
+export function profileChecks(configDir) {
+    const dir = profileDir(configDir);
+    if (!existsSync(dir))
+        return [];
+    const parts = [];
+    if (readRules(configDir).replace(/<!--[\s\S]*?-->/g, '').trim())
+        parts.push('rules');
+    try {
+        if (renderClaudeSettings(configDir) !== null)
+            parts.push('Claude settings');
+    }
+    catch (err) {
+        return [{ name: 'agent profile', status: 'fail', detail: `${CLAUDE_SETTINGS}: ${err.message}`, fix: `fix ${join(dir, CLAUDE_SETTINGS)}` }];
+    }
+    return [parts.length ? { name: 'agent profile', status: 'ok', detail: parts.join(', ') } : { name: 'agent profile', status: 'warn', detail: 'empty', fix: `add rules to ${join(dir, RULES_FILE)}` }];
+}

package/dist/runner.d.ts

@@ -1,4 +1,4 @@
-import { type AgentsConfig, type Workflow, type Project, type StepId, type Trigger } from './config.ts';
+import { type AgentsConfig, type Workflow, type Project, type Trigger } from './config.ts';
 import type { Card } from './linear.ts';
 import { type Tracker, type Trackers } from './tracker.ts';
 export interface RunContext {
@@ -10,7 +10,7 @@ export interface RunContext {
 }
 export declare function summarize(output: string): string;
 export declare function runCard(card: Card, trigger: Trigger, workflowName: string, workflow: Workflow, project: Project, rc: RunContext, opts?: {
-    from?: StepId;
+    from?: string;
 }): Promise<'verified' | 'changes' | 'parked'>;
 type Job = {
     card: Card;
@@ -25,6 +25,6 @@ export declare function nextJob(rc: RunContext, only?: string, workflowName?: st
 export declare function cancelCard(tracker: Tracker, configDir: string, cardId: string, label: string, source?: 'linear' | 'voidtrack'): Promise<boolean>;
 export declare function tick(rc: RunContext, only?: string, opts?: {
     workflow?: string;
-    from?: StepId;
+    from?: string;
 }): Promise<number>;
 export {};

package/dist/runner.js

@@ -1,16 +1,14 @@
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import { basename, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isStatusLabel, latestPlan, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
-import { STEPS, agentsDir, hasWork, isCardTrigger, isProducer } from "./config.js";
+import { agentsDir, hasWork, isCardTrigger, resolveStep, stepId, stepIdLabel } from "./config.js";
 import { lastDue, parseCron } from "./cron.js";
 import { runAgent, stopAgents } from "./engine.js";
-import { commitsAhead, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
+import { commitsAhead, enforceCommitPolicy, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
 import { noTracker } from "./tracker.js";
 import { recall, vaultPath } from "./memory.js";
+import { claudeSettingsFile, readRules, rulesSection } from "./profile.js";
 import { bootTime, clearCurrent, isPaused, ours, readCurrent, readPending, writeCurrent, writePending, writeRun, readCronState, writeCronState } from "./state.js";
-const packDir = fileURLToPath(new URL('../pack/', import.meta.url));
-const skill = (name) => readFileSync(join(packDir, name, 'SKILL.md'), 'utf8');
 const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
 class Park extends Error {
 }
@@ -37,7 +35,10 @@ export function summarize(output) {
 }
 // The run in progress, so a cancel signal can mark it.
 let active = null;
-const isVerdict = (s) => STEPS[s].output === 'verdict';
+const isVerdict = (d) => d.output === 'verdict';
+const isProducer = (d) => d.output === 'plan' || d.output === 'commits';
+// The card label for a step: its own for a built-in step, a generic one otherwise.
+const stageOf = (d) => LABELS.stage[d.builtin ?? ''] ?? LABELS.working;
 // One card through a trigger's workflow. Steps run in order. A failed check (or a
 // run of consecutive checks) sends its findings back to the nearest earlier
 // step that produces something, Plan or Dev, and the workflow continues from
@@ -50,7 +51,9 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     const runDir = join(agentsDir(rc.configDir), 'runs', card.identifier, stamp());
     mkdirSync(runDir, { recursive: true });
     const say = (line) => log(`${card.identifier} ${line}`);
-    const steps = workflow.steps;
+    // Write back settings apply to card runs; a scheduled run has nothing to write to.
+    const writeBack = isCardTrigger(trigger) ? (workflow.writeBack ?? {}) : {};
+    const labelsOn = writeBack.labels !== false;
     const startedAt = new Date().toISOString();
     const record = { card: card.identifier, title: card.title, url: card.url || undefined, workflow: workflowName, trigger: label || (trigger.source === 'cron' ? trigger.schedule : ''), source: trigger.source, steps: [], outcome: 'running', startedAt };
     active = { record, runDir };
@@ -61,8 +64,8 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     const mark = (step) => writeCurrent(rc.configDir, { pid: process.pid, card: card.identifier, title: card.title, workflow: workflowName, step, round: loops, startedAt, runDir, source: trigger.source });
     // Written before the first tracker call, so a cancel always knows the card.
     mark('Starting');
-    const begin = (step) => {
-        const rec = { step, label: STEPS[step].label, startedAt: new Date().toISOString() };
+    const begin = (def) => {
+        const rec = { step: def.id, label: def.label, startedAt: new Date().toISOString() };
         record.steps.push(rec);
         mark(rec.label);
         save();
@@ -89,7 +92,13 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     const setRound = (n) => {
         loops = n;
     };
-    const stage = (name, round) => linear.setLabels(card, stageLabels(card.labels, label, name, round));
+    const stage = async (name, round) => {
+        if (labelsOn)
+            await linear.setLabels(card, stageLabels(card.labels, label, name, round));
+    };
+    // How a run ends on the card: a stage label, or with labels off only the
+    // trigger taken away so the card is not picked up again.
+    const endLabels = (name, round) => linear.setLabels(card, labelsOn ? stageLabels(card.labels, label, name, round) : card.labels.filter((l) => l !== label));
     // The tracker hears from the runner twice: the plan once it has passed review,
     // and one final comment. Findings stay here until the final one.
     let lastFindings = '';
@@ -103,40 +112,51 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     async function park(reason) {
         say(`parked: ${reason}`);
         const comment = `**Parked:** ${reason}${lastFindings ? `\n\n${lastFindings}` : ''}\n\nFix the cause, then add \`${label}\` again to retry.`;
-        const add = [LABELS.parked, ...(loops ? [LABELS.version(loops)] : [])];
+        const add = labelsOn ? [LABELS.parked, ...(loops ? [LABELS.version(loops)] : [])] : [];
         let commented = false;
         try {
             await postPlan();
             await linear.comment(card, comment);
             commented = true;
-            await linear.setLabels(card, stageLabels(card.labels, label, LABELS.parked, loops || undefined));
+            await endLabels(LABELS.parked, loops || undefined);
         }
         catch (err) {
             if (!isCardTrigger(trigger))
                 return done('parked', reason);
             say(`could not reach ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} to park it (${err.message}). Will retry next minute.`);
             // An empty comment is skipped on retry, so it is not posted twice.
-            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: true, source: trigger.source }]);
+            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: labelsOn, source: trigger.source }]);
         }
         return done('parked', reason);
     }
     try {
         if (!existsSync(join(project.path, '.git')))
             throw new Park(`The project folder ${project.path} is not a git repository on this Mac.`);
-        const from = opts.from ? steps.indexOf(opts.from) : 0;
+        const steps = workflow.steps.map((s) => resolveStep(s, config, config.folders?.[workflowName]));
+        const from = opts.from ? steps.findIndex((d) => d.id === opts.from) : 0;
         if (from < 0)
-            throw new Park(`Workflow ${workflowName} has no ${STEPS[opts.from].label} step.`);
+            throw new Park(`Workflow ${workflowName} has no ${stepIdLabel(opts.from)} step.`);
         // A scheduled run has no card to plan on, so its task is the plan unless a Plan step writes one.
         let plan = isCardTrigger(trigger) ? latestPlan(await linear.comments(card.identifier)) : card.description ?? null;
-        const firstPlan = steps.indexOf('vs-plan', from);
-        const needsPlan = steps.findIndex((s, n) => n >= from && (s === 'vs-dev' || s === 'vs-plan-review'));
+        const firstPlan = steps.findIndex((d, n) => n >= from && d.output === 'plan');
+        // A check before any commits is a check on the plan, like Plan review.
+        const needsPlan = steps.findIndex((d, n) => n >= from && (d.output === 'commits' || (d.output === 'verdict' && d.builtin !== 'vs-qa')));
         if (!plan && needsPlan >= 0 && (firstPlan < 0 || firstPlan > needsPlan)) {
             throw new Park('No plan comment (starting with "## Plan") was found. Publish a plan first, or start the workflow with Plan.');
         }
-        await stage(LABELS.stage[steps[from]]);
+        await stage(stageOf(steps[from]));
         const base = project.base || defaultBranch(project.path);
         const vault = vaultPath(rc.configDir);
-        const known = [recall(rc.selfCommand, rc.configDir, `${workflow.project} ${card.title}\n${card.description ?? ''}`), vault ? memoryNote(vault) : ''].filter(Boolean).join('\n\n');
+        // Your profile rides along on every step: rules in the prompt, Claude settings as a file.
+        let settingsFile;
+        try {
+            settingsFile = claudeSettingsFile(rc.configDir, runDir);
+        }
+        catch (err) {
+            throw new Park(`Your agent profile's Claude settings are broken: ${err.message}`);
+        }
+        const rules = rulesSection(readRules(rc.configDir));
+        const known = [recall(rc.selfCommand, rc.configDir, `${workflow.project} ${card.title}\n${card.description ?? ''}`), vault ? memoryNote(vault) : '', rules].filter(Boolean).join('\n\n');
         const worktree = join(agentsDir(rc.configDir), 'worktrees', card.identifier);
         ensureWorktree(project.path, worktree, card.branchName, base);
         say(`working in ${worktree} on ${card.branchName}`);
@@ -145,13 +165,12 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         let prUrl = '';
         let logs = 0;
         const planText = () => plan ?? '(No plan was posted on this card. Check the work against the card itself.)';
-        const timeoutMs = config.timeoutMinutes * 60_000;
         const logFile = (name) => join(runDir, `${String(logs++).padStart(2, '0')}-${name}.log`);
-        async function check(step, round) {
-            const label = STEPS[step].label;
-            const rec = begin(step);
+        async function check(def, round) {
+            const label = def.label;
+            const rec = begin(def);
             let ciNote = '';
-            if (step === 'vs-qa') {
+            if (def.builtin === 'vs-qa') {
                 if (commitsAhead(worktree, base) === 0) {
                     end(rec, 'SKIP', 'No changes on the branch yet.');
                     return { step: label, verdict: 'SKIP', report: 'No changes on the branch yet.' };
@@ -179,12 +198,12 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                     ciNote = ci.verdict === 'SHIP' ? '# CI\n\nCI passed on this branch.' : '# CI\n\nThis repo has no CI checks.';
                 }
             }
-            const log = logFile(step);
+            const log = logFile(def.id);
             const r = await runAgent({
-                engine: config.engine, model: config.models.review, cwd: worktree, vault, write: step === 'vs-qa', logFile: log, timeoutMs,
-                prompt: buildPrompt({ skill: skill(step), card, plan: planText(), base, round, extra: [known, ciNote, UNATTENDED].filter(Boolean).join('\n\n') }),
+                engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
+                prompt: buildPrompt({ skill: def.prompt(), card, plan: planText(), base, round, extra: [known, ciNote, UNATTENDED].filter(Boolean).join('\n\n') }),
             });
-            if (step === 'vs-qa')
+            if (def.builtin === 'vs-qa')
                 resetWorktree(worktree);
             const verdict = parseVerdict(r.output);
             end(rec, verdict, r.output, log);
@@ -192,18 +211,18 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         }
         let i = from;
         while (i < steps.length) {
-            const step = steps[i];
-            say(`${STEPS[step].label}`);
-            if (isVerdict(step)) {
+            const def = steps[i];
+            say(def.label);
+            if (isVerdict(def)) {
                 const [start, end] = verdictBlock(steps, i, isVerdict);
                 const target = fixTarget(steps, start, isProducer);
                 const producer = target >= 0 ? steps[target] : undefined;
                 // The round being checked: how many times its producer has run.
-                const round = Math.max(producer === 'vs-plan' ? runs.plan : runs.dev, 1);
+                const round = Math.max(producer?.output === 'plan' ? runs.plan : runs.dev, 1);
                 setRound(round);
                 const results = [];
                 for (const s of steps.slice(start, end)) {
-                    await stage(LABELS.stage[s], round);
+                    await stage(stageOf(s), round);
                     results.push(await check(s, round));
                 }
                 if (qaPassed(results)) {
@@ -215,26 +234,26 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 if (target < 0) {
                     await postPlan();
                     await linear.comment(card, `**Changes needed.**\n\n${notes}`);
-                    await linear.setLabels(card, stageLabels(card.labels, label, LABELS.changes, round));
+                    await endLabels(LABELS.changes, round);
                     say('changes requested');
                     return done('changes');
                 }
                 // Rounds caps how many times Plan or Dev runs, counting the first.
                 if (round >= workflow.maxRounds) {
-                    throw new Park(`Checks still failed after ${round} ${producer === 'vs-plan' ? 'plan' : 'dev'} rounds.${prUrl ? ` PR: ${prUrl}` : ''}`);
+                    throw new Park(`Checks still failed after ${round} ${producer?.output === 'plan' ? 'plan' : 'dev'} rounds.${prUrl ? ` PR: ${prUrl}` : ''}`);
                 }
                 findings.set(target, notes);
                 i = target;
                 continue;
             }
-            if (step === 'vs-plan') {
+            if (def.output === 'plan') {
                 setRound(runs.plan + 1);
-                await stage(LABELS.stage[step], runs.plan + 1);
-                const rec = begin(step);
-                const log = logFile('plan');
+                await stage(stageOf(def), runs.plan + 1);
+                const rec = begin(def);
+                const log = logFile(def.builtin ? 'plan' : def.id);
                 const r = await runAgent({
-                    engine: config.engine, model: config.models.dev, cwd: worktree, vault, write: false, logFile: log, timeoutMs,
-                    prompt: buildPrompt({ skill: skill('vs-plan'), card, plan: plan ?? '(none yet, you are writing it)', base, round: runs.plan + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
+                    engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
+                    prompt: buildPrompt({ skill: def.prompt(), card, plan: plan ?? '(none yet, you are writing it)', base, round: runs.plan + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
                 });
                 const result = parseDevResult(r.output);
                 end(rec, result.status === 'blocked' ? 'blocked' : 'done', r.output, log);
@@ -244,22 +263,22 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 planToPost = plan;
                 runs.plan++;
             }
-            else if (step === 'vs-publish') {
+            else if (def.output === 'publish') {
                 await postPlan();
-                const rec = begin(step);
+                const rec = begin(def);
                 push(worktree, card.branchName);
                 end(rec, 'pushed');
             }
-            else if (step === 'vs-dev') {
+            else if (def.output === 'commits') {
                 await postPlan();
                 setRound(runs.dev + 1);
-                await stage(LABELS.stage[step], runs.dev + 1);
-                const rec = begin(step);
-                const log = logFile('dev');
+                await stage(stageOf(def), runs.dev + 1);
+                const rec = begin(def);
+                const log = logFile(def.builtin ? 'dev' : def.id);
                 const before = headSha(worktree);
                 const dev = await runAgent({
-                    engine: config.engine, model: config.models.dev, cwd: worktree, vault, write: true, logFile: log, timeoutMs,
-                    prompt: buildPrompt({ skill: skill('vs-dev'), card, plan: planText(), base, round: runs.dev + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
+                    engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
+                    prompt: buildPrompt({ skill: def.prompt(), card, plan: planText(), base, round: runs.dev + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
                 });
                 const result = parseDevResult(dev.output);
                 end(rec, result.status === 'blocked' ? 'blocked' : 'done', dev.output, log);
@@ -271,23 +290,42 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 // just check the same commit again.
                 if (runs.dev > 0 && headSha(worktree) === before)
                     throw new Park('The dev agent made no new commits this round.');
+                // Only this round's commits, which are not pushed yet.
+                const fixed = enforceCommitPolicy(worktree, before, config.commits ?? {});
+                if (fixed)
+                    say(`applied the commit policy to ${fixed} commit${fixed === 1 ? '' : 's'}`);
                 push(worktree, card.branchName);
                 prUrl = ensureDraftPr(worktree, card.branchName, base, `${card.identifier}: ${card.title}`, card.url);
                 record.prUrl = prUrl;
                 save();
                 runs.dev++;
             }
+            else {
+                // A step with no output the workflow reads: it runs once and must finish.
+                await stage(stageOf(def), loops || undefined);
+                const rec = begin(def);
+                const log = logFile(def.id);
+                const r = await runAgent({
+                    engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
+                    prompt: buildPrompt({ skill: def.prompt(), card, plan: plan ?? '(none)', base, round: loops || 1, extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
+                });
+                end(rec, r.ok ? 'done' : 'failed', r.output, log);
+                if (!r.ok)
+                    throw new Park(`The ${def.label} step failed or timed out.`);
+            }
             findings.delete(i);
             i++;
         }
         await postPlan();
-        let moved = false;
-        if (hasWork(workflow)) {
+        // Unset moves a card with commits to reviewState; a state always moves it; null never does.
+        const state = writeBack.state === undefined ? (hasWork(workflow) ? config.reviewState : null) : writeBack.state;
+        if (hasWork(workflow))
             markReady(worktree, card.branchName);
-            moved = await linear.moveTo(card, config.reviewState);
+        const moved = state ? await linear.moveTo(card, state) : true;
+        await endLabels(LABELS.verified, loops || undefined);
+        if (writeBack.comment !== false) {
+            await linear.comment(card, `**All checks passed.**${prUrl ? ` PR ready: ${prUrl}` : ''}${!moved ? `\n\n(No "${state}" state on this team, so the card was not moved.)` : ''}`);
         }
-        await linear.setLabels(card, stageLabels(card.labels, label, LABELS.verified, loops || undefined));
-        await linear.comment(card, `**All checks passed.**${prUrl ? ` PR ready: ${prUrl}` : ''}${hasWork(workflow) && !moved ? `\n\n(No "${config.reviewState}" state on this team, so the card was not moved.)` : ''}`);
         say('verified');
         return done('verified');
     }
@@ -504,8 +542,8 @@ export async function tick(rc, only, opts = {}) {
             rc.log(`Workflow ${job.workflow} points at a missing project ${workflow.project}. Run vsf agents workflow edit to fix it.`);
             return 1;
         }
-        if (opts.from && !workflow.steps.includes(opts.from)) {
-            rc.log(`Workflow ${job.workflow} has no ${STEPS[opts.from].label} step.`);
+        if (opts.from && !workflow.steps.some((s) => stepId(s) === opts.from)) {
+            rc.log(`Workflow ${job.workflow} has no ${stepIdLabel(opts.from)} step.`);
             return 2;
         }
         const outcome = await runCard(job.card, job.trigger, job.workflow, workflow, project, rc, { from: opts.from });

package/dist/state.d.ts

@@ -1,4 +1,4 @@
-import { type StepId, type Trigger } from './config.ts';
+import { type Trigger } from './config.ts';
 export interface Current {
     pid: number;
     card?: string;
@@ -32,7 +32,7 @@ export declare function readPending(configDir: string): Pending[];
 export declare function writePending(configDir: string, pending: Pending[]): void;
 export type Outcome = 'running' | 'verified' | 'changes' | 'parked' | 'cancelled';
 export interface StepRecord {
-    step: StepId;
+    step: string;
     label: string;
     startedAt: string;
     endedAt?: string;

package/dist/workflow.d.ts

@@ -47,6 +47,6 @@ export interface PromptInput {
     extra?: string;
 }
 export declare function buildPrompt(p: PromptInput): string;
-export declare function verdictBlock<T extends string>(steps: T[], i: number, isVerdict: (s: T) => boolean): [number, number];
-export declare function fixTarget<T extends string>(steps: T[], blockStart: number, isProducer: (s: T) => boolean): number;
+export declare function verdictBlock<T>(steps: T[], i: number, isVerdict: (s: T) => boolean): [number, number];
+export declare function fixTarget<T>(steps: T[], blockStart: number, isProducer: (s: T) => boolean): number;
 export declare function planBody(output: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidlabs.gg/voidshift-agents",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Agents for Claude Code and Codex that plan, build and QA Linear cards, chained and run in the background.",
   "license": "Apache-2.0",
   "repository": {