@gilangjavier/agent-taskfile

Validate and normalize AI agent task files (JSON/YAML) with deterministic lint rules.

Why

Agent task files are often hand-written and drift into footguns: missing timeouts, duplicate step ids, dangerous shell snippets, and hardcoded secrets. agent-taskfile gives a small, deterministic validator + normalizer usable by both AI agents and humans.

1) For AI agents (copy-paste friendly)

Install (ephemeral)

npm i -D @gilangjavier/agent-taskfile

Validate with deterministic machine-readable output

npx agent-taskfile validate ./task.yaml --strict --format json

Expected behavior:

• Exit code 0 => no errors/warnings in strict mode.
• Exit code 1 => at least one error or warning.
• JSON output contains: valid, summary, issueCount, issues[].

Normalize then validate again

npx agent-taskfile normalize ./task.yaml --write
npx agent-taskfile validate ./task.yaml --strict --format json

2) For humans

Install

npm i -g @gilangjavier/agent-taskfile

Usage

agent-taskfile validate ./task.yaml
agent-taskfile normalize ./task.yaml --write

Commands

agent-taskfile validate <file> [--strict] [--format text|json]
agent-taskfile normalize <file> [--write] [--format json|yaml]

Example task file

title: Release prep
goal: Validate and run release checks safely
deterministic: true
env:
  GITHUB_TOKEN:
    fromEnv: GITHUB_TOKEN
steps:
  - id: test
    run: npm test
    timeoutSec: 600
  - uses: npm/publish
    with:
      tag: next

Lint rules included (MVP)

• Required fields: title, goal, non-empty steps.
• Step action rules: exactly one of run or uses.
• Duplicate steps[].id detection.
• Missing timeoutSec warning (normalize defaults to 300).
• Dangerous command heuristic warnings.
• Hardcoded secret heuristic warnings in env values.
• Non-deterministic command warnings when deterministic is true.

Library usage

import { validateTask, normalizeTask } from "@gilangjavier/agent-taskfile";

const result = validateTask(taskObject, { strict: true });
if (!result.valid) {
  console.error(result.issues);
}

const normalized = normalizeTask(result.task!);

Development

npm ci
npm run typecheck
npm test
npm run build

License

MIT