@voidlabs.gg/voidshift-agents 0.4.4 → 0.5.0

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
@@ -102,12 +127,35 @@ vsf memory status          # the vault and where recall is on
 vsf memory search WORDS    # notes recall would bring up
 vsf memory try "a prompt"  # exactly what recall would add to that prompt
 vsf memory check           # notes missing from INDEX.md, broken links
+vsf memory sync            # pull and push the vault through its git remote
 vsf memory on | off        # turn recall on or off
 ```
 
+To share the vault between machines, make it a git repository with a remote
+named `origin` (any host; a private repository). `vsf memory sync` commits new
+notes, rebases onto the remote and pushes. It also runs in the background from
+the recall hook when the last sync is over ten minutes old, and the agents
+runner syncs before and after every run. When a note changed on both sides,
+the remote's version stays and this machine's copy is saved beside it as
+`note.conflict-<machine>-<time>.md`, so nothing is lost.
+
 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
@@ -141,8 +189,12 @@ pnpm test
 node packages/cli/src/main.ts
 ```
 
-Node 22.18 or newer runs the TypeScript sources directly. Releases are cut by
-pushing a `v*` tag; CI publishes every package at that version.
+Node 22.18 or newer runs the TypeScript sources directly. Each package
+releases on its own: bump its `package.json` and push `agents-v0.5.0` (or
+`cli-v`, `memory-v`, `awake-v`), and CI publishes only that package. A plain
+`v*` tag publishes all four at one version. Tools declare the CLI contract
+they were built for; a CLI that is too old refuses to load them and says to
+run `vsf update`.
 
 ## License
 

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 };
@@ -1023,6 +1042,7 @@ const homeCommands = {
 const sameModels = (a, b) => a.dev === b.dev && a.review === b.review;
 const agents = {
     name: 'agents',
+    contract: 1,
     summary: 'Agents for Claude Code and Codex that plan, build and QA Linear cards',
     config: {
         read: (dir) => readAgentsConfig(dir),
@@ -1062,6 +1082,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 +1144,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 +1161,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 +1175,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;