@syedshoaib/agent-ready 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-ready contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# agent-ready
+
+> Make every ticket ready for AI coding agents.
+
+`agent-ready` is a Definition-of-Ready linter that runs **before** an AI coding agent picks up a ticket. It answers one question: *is this issue actually ready for an agent to work on?*
+
+If the answer is no, it tells you exactly what's missing — in seconds, in CI, in the PR comment, before any tokens are spent.
+
+```bash
+$ npx @syedshoaib/agent-ready check examples/tickets/bad-ticket.json
+
+✗ PROJ-1234  not ready  (4 blocker(s), 6 warning(s))
+
+  ✗ has-acceptance-criteria       No acceptance criteria found (need at least 1)
+  ⚠ has-definition-of-done        No Definition of Done found
+  ✗ has-repo-target               Ticket does not specify the target repo
+  ✗ has-risk-classification       No risk classification label
+  ⚠ has-test-expectations         No test expectations described
+  ⚠ no-ambiguous-verbs            Ambiguous verb(s): improve, make it better
+  ✗ body-min-length               Body too short: 91 chars (need >= 100)
+  ⚠ no-tribal-knowledge           Tribal-knowledge phrase(s): you know what i mean
+  ⚠ t-shirt-size-present          No t-shirt size estimate
+  ⚠ has-design-link               UI ticket has no design link
+```
+
+```bash
+$ npx @syedshoaib/agent-ready check examples/tickets/good-ticket.json
+
+✓ PROJ-2042  ready  (10 checks passed)
+```
+
+## Why this exists
+
+Every team adopting Copilot, Cursor, Claude Code, or Codex agents hits the same wall:
+
+> **Garbage tickets → garbage PRs.**
+
+Agents are confident and fast. Without a clear ticket, that's a liability — they invent context, miss the real requirement, and silently burn tokens.
+
+`agent-ready` is the cheap, automated gate that catches this. It runs in 50ms, has zero infrastructure, and plugs into Issue templates and PR workflows everyone already uses.
+
+It's the **front door** of the agentic SDLC: prove the ticket is ready before any agent touches it.
+
+## What it checks (v0 default rule pack — 10 rules)
+
+| Rule | What it looks for |
+|---|---|
+| `has-acceptance-criteria` | At least N acceptance criteria (numbered list, checklist, or Given/When) |
+| `has-definition-of-done` | A DoD section in the body |
+| `has-repo-target` | `repo:` in the body or a `repo:<name>` label |
+| `has-risk-classification` | A `risk:low`/`risk:medium`/`risk:high` label |
+| `has-design-link` | Figma/Ardoq/Miro/Excalidraw link present when the ticket has a `ui`/`ux`/`frontend` label |
+| `has-test-expectations` | "How to verify" / test plan / Playwright / Jest / Pytest mentioned |
+| `no-ambiguous-verbs` | Flags vague verbs (`improve`, `optimize`, `clean up`, `refactor`, `enhance`, …) |
+| `body-min-length` | Body is at least 100 characters (configurable) |
+| `no-tribal-knowledge` | Flags phrases like "as discussed", "you know what I mean", "the usual way" |
+| `t-shirt-size-present` | `size:` in the body or a `size:S|M|L|XL` label |
+
+Plus user-defined custom rules of `type: regex` (see [Rule pack format](#rule-pack-format)).
+
+Every rule can be enabled, disabled, or tuned in a YAML rule pack.
+
+> **Planned for v0.1 (not yet implemented):** `links-resolve`, `restricted-paths-declared`, plus `path_recommendation` / `context_tier` / `risk_classification` output fields, Jira/Linear adapters, SARIF output, an `agent-ready` label setter, and a Node plugin loader for custom rules.
+
+## Install
+
+```bash
+# One-off use with a local ticket file
+npx @syedshoaib/agent-ready check <path-to-ticket-json>
+
+# Or fetch a real GitHub Issue
+npx @syedshoaib/agent-ready check owner/repo#123 --adapter github
+
+# Or install globally
+npm i -g @syedshoaib/agent-ready
+agent-ready check ./ticket.json
+```
+
+> The CLI supports local JSON tickets and GitHub Issues. GitHub auth uses `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`. Native Jira/Linear CLI adapters are planned for v0.1.
+
+## Usage
+
+```bash
+# Lint a ticket from a local JSON file
+agent-ready check examples/tickets/bad-ticket.json
+agent-ready check examples/tickets/good-ticket.json
+
+# Lint a GitHub Issue
+agent-ready check Schoaib/agent-ready#1 --adapter github
+agent-ready check https://github.com/Schoaib/agent-ready/issues/1 --adapter github
+
+# Use a custom rule pack
+agent-ready check ./ticket.json --rules ./my-rules.yaml
+
+# Output formats
+agent-ready check ./ticket.json --format text       # default
+agent-ready check ./ticket.json --format markdown   # PR comment
+agent-ready check ./ticket.json --format json       # machine-readable
+```
+
+Exit codes: `0` ready · `1` not ready · `2` usage error.
+
+## GitHub Action
+
+Drop this into `.github/workflows/agent-ready.yml`:
+
+```yaml
+name: Agent-Ready Check
+on:
+  issues:
+    types: [opened, edited, labeled]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: Schoaib/agent-ready@v0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          rules: .agent-ready/rules.yaml   # optional
+          comment-on-issue: true
+          fail-on-not-ready: true
+```
+
+The action fetches the triggering issue from the GitHub API, normalizes it into the linter's ticket shape, runs the lint, posts the result as a comment, and writes outputs (`ready`, `failed-count`, `warnings-count`). When `fail-on-not-ready: true`, the step exits non-zero so the issue check shows red until the ticket is fixed.
+
+> **Planned for v0.1:** the action will also set/remove an `agent-ready` label on the issue so downstream agent workflows can listen for the label rather than parsing comment text.
+
+## Rule pack format
+
+Rule packs are plain YAML. Mix built-ins with custom rules of `type: regex`:
+
+```yaml
+# .agent-ready/rules.yaml
+version: 1
+extends: default
+
+rules:
+  has-acceptance-criteria:
+    enabled: true
+    min_count: 2
+    severity: error
+
+  no-ambiguous-verbs:
+    enabled: true
+    severity: warn
+    extra_terms: [tidy, polish, modernize]
+
+  custom-mentions-jira-epic:
+    type: regex
+    pattern: 'EPIC-\d+'
+    field: body
+    severity: error
+    message: "Ticket must link to a parent epic (EPIC-XXX)"
+```
+
+JSON Schemas are published in [`schema/`](schema/) — both the rule pack format ([`rule-pack.schema.json`](schema/rule-pack.schema.json)) and the CLI output ([`output.schema.json`](schema/output.schema.json)). The output schema is stable across versions; downstream tools (e.g. [Gatepack](#how-it-composes-with-the-rest-of-your-stack)) can safely consume it.
+
+## How it composes with the rest of your stack
+
+`agent-ready` is the **first** gate. It doesn't replace your existing tools — it makes them work better.
+
+| Tool | What it does | When it runs |
+|---|---|---|
+| **`agent-ready`** | Is this *ticket* ready for an agent? | Issue open → before agent picks up |
+| Spec Kit / Linear specs | Authoring help for the spec itself | While writing the ticket |
+| Your AI coding agent | Implements the change | After `agent-ready` passes |
+| Gatepack *(planned)* | Per-PR signed evidence bundle (includes `agent-ready` pre-flight result) | After agent submits PR |
+| Evidence Gate Action | Traditional CI evidence (SBOM, SAST, tests) | During CI |
+| OPA / your policy engine | Decision enforcement | Throughout |
+
+## Status
+
+**v0.0.2.** Schemas, CLI, file and GitHub adapters, 10 built-in rules, regex custom rules, JSON/markdown/text renderers, GitHub Action (Docker-based), and a CI workflow that runs the bad/good demo on every PR. All verified end-to-end.
+
+## Releases
+
+GitHub Action users should pin either:
+
+```yaml
+- uses: Schoaib/agent-ready@v0.0.2  # exact release
+- uses: Schoaib/agent-ready@v0      # latest v0 release
+```
+
+The Marketplace listing is published from GitHub Releases. For each release, verify CI, create the version tag, publish the release, and select **Publish this Action to the GitHub Marketplace**.
+
+### Roadmap
+
+**v0.1 — honest the rest of the way**
+- Native CLI adapters for Jira and Linear
+- `links-resolve` rule
+- `restricted-paths-declared` rule (links to OPA's `restricted-paths.rego`)
+- `path_recommendation` (A/B/C), `context_tier` (T1/T2/T3), and `risk_classification` as first-class output fields — driven by a rule pack
+- `agent-ready` label setter on the issue (so agent workflows can listen for the label)
+- SARIF output format
+- Output fields for Gatepack ingestion: rule pack version + hash, source URL, adapter metadata
+- LLM judge for `no-ambiguous-verbs` (opt-in)
+
+**v0.2**
+- VS Code extension: lint as you type the issue
+- Node plugin loader for custom rules (beyond regex)
+
+**v0.3**
+- Companion product `gatepack` — signed per-PR evidence bundle that includes the `agent-ready` pre-flight result as one of its input sources
+
+## Contributing
+
+Rules are the easiest contribution path. One rule = one entry in `src/rules/built-in.ts` + one demonstration in `examples/tickets/`. PRs welcome.
+
+## License
+
+MIT.

package/dist/adapters/file.d.ts

@@ -0,0 +1,2 @@
+import type { Ticket } from "../types.js";
+export declare function loadTicketFromFile(path: string): Promise<Ticket>;

package/dist/adapters/file.js

@@ -0,0 +1,15 @@
+import { readFile } from "node:fs/promises";
+export async function loadTicketFromFile(path) {
+    const raw = await readFile(path, "utf8");
+    const obj = JSON.parse(raw);
+    if (!obj.id || !obj.title) {
+        throw new Error(`Invalid ticket file ${path}: missing 'id' or 'title'`);
+    }
+    return {
+        id: String(obj.id),
+        title: String(obj.title),
+        body: String(obj.body ?? ""),
+        labels: Array.isArray(obj.labels) ? obj.labels.map(String) : [],
+        url: obj.url
+    };
+}

package/dist/adapters/github.d.ts

@@ -0,0 +1,2 @@
+import type { Ticket } from "../types.js";
+export declare function loadTicketFromGitHub(target: string): Promise<Ticket>;

package/dist/adapters/github.js

@@ -0,0 +1,70 @@
+import { execFileSync } from "node:child_process";
+function parseGitHubTarget(target) {
+    const shorthand = target.match(/^([^/\s#]+)\/([^/\s#]+)#(\d+)$/);
+    if (shorthand) {
+        return {
+            owner: shorthand[1],
+            repo: shorthand[2],
+            issueNumber: Number(shorthand[3])
+        };
+    }
+    const url = target.match(/^https:\/\/github\.com\/([^/\s]+)\/([^/\s]+)\/issues\/(\d+)(?:[/?#].*)?$/);
+    if (url) {
+        return {
+            owner: url[1],
+            repo: url[2],
+            issueNumber: Number(url[3])
+        };
+    }
+    throw new Error("Invalid GitHub target. Use owner/repo#123 or https://github.com/owner/repo/issues/123");
+}
+function githubToken() {
+    const envToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    if (envToken)
+        return envToken;
+    try {
+        return execFileSync("gh", ["auth", "token"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"]
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeLabels(labels) {
+    return labels
+        .map((label) => {
+        if (typeof label === "string")
+            return label;
+        return label.name ?? "";
+    })
+        .filter(Boolean);
+}
+export async function loadTicketFromGitHub(target) {
+    const { owner, repo, issueNumber } = parseGitHubTarget(target);
+    const token = githubToken();
+    const headers = {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "agent-ready"
+    };
+    if (token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+    const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}`, { headers });
+    const issue = (await res.json());
+    if (!res.ok) {
+        const detail = issue.message ? `: ${issue.message}` : "";
+        throw new Error(`GitHub issue fetch failed (${res.status})${detail}`);
+    }
+    if (!issue.title) {
+        throw new Error(`GitHub issue ${owner}/${repo}#${issueNumber} has no title`);
+    }
+    return {
+        id: `#${issue.number}`,
+        title: issue.title,
+        body: issue.body ?? "",
+        labels: normalizeLabels(issue.labels),
+        url: issue.html_url
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { lintTicket } from "./lint.js";
+import { loadTicketFromFile } from "./adapters/file.js";
+import { loadTicketFromGitHub } from "./adapters/github.js";
+import { renderMarkdown, renderText } from "./render/markdown.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function parseArgs(argv) {
+    const args = { command: "help", adapter: "file", format: "text" };
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--adapter")
+            args.adapter = argv[++i];
+        else if (a === "--rules")
+            args.rules = argv[++i];
+        else if (a === "--format")
+            args.format = argv[++i];
+        else if (a === "-h" || a === "--help")
+            args.command = "help";
+        else if (a === "-v" || a === "--version")
+            args.command = "version";
+        else
+            rest.push(a);
+    }
+    if (rest[0] === "check" && rest[1]) {
+        args.command = "check";
+        args.target = rest[1];
+    }
+    else if (rest[0] === "help") {
+        args.command = "help";
+    }
+    else if (rest[0]) {
+        args.command = "check";
+        args.target = rest[0];
+    }
+    return args;
+}
+async function loadRulePack(path) {
+    const defaultPath = resolve(__dirname, "..", "rule-packs", "default.yaml");
+    const file = path ?? defaultPath;
+    const raw = await readFile(file, "utf8");
+    const pack = parseYaml(raw);
+    return { pack, name: path ? file : "default" };
+}
+function usage() {
+    return `agent-ready — Make every ticket ready for AI coding agents.
+
+Usage:
+  agent-ready check <ticket-or-file> [--adapter file|github|jira|linear] [--rules <path>] [--format text|markdown|json]
+  agent-ready --version
+  agent-ready --help
+
+Examples:
+  agent-ready check examples/tickets/bad-ticket.json
+  agent-ready check examples/tickets/good-ticket.json --format markdown
+  agent-ready check owner/repo#123 --adapter github
+  agent-ready check https://github.com/owner/repo/issues/123 --adapter github
+`;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.command === "version") {
+        console.log("0.0.1");
+        return 0;
+    }
+    if (args.command === "help" || !args.target) {
+        console.log(usage());
+        return 0;
+    }
+    if (args.adapter === "jira" || args.adapter === "linear") {
+        console.error(`Adapter '${args.adapter}' is not implemented yet. Use --adapter file or --adapter github.`);
+        return 2;
+    }
+    const ticket = args.adapter === "github"
+        ? await loadTicketFromGitHub(args.target)
+        : await loadTicketFromFile(args.target);
+    const { pack, name } = await loadRulePack(args.rules);
+    const out = lintTicket(ticket, pack, { adapter: args.adapter, rulePackName: name });
+    if (args.format === "json")
+        console.log(JSON.stringify(out, null, 2));
+    else if (args.format === "markdown")
+        console.log(renderMarkdown(out));
+    else
+        console.log(renderText(out));
+    return out.ready ? 0 : 1;
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    console.error(`agent-ready: ${err?.message ?? err}`);
+    process.exit(2);
+});

package/dist/lint.d.ts

@@ -0,0 +1,5 @@
+import type { LintOutput, RulePack, Ticket } from "./types.js";
+export declare function lintTicket(ticket: Ticket, pack: RulePack, opts: {
+    adapter: string;
+    rulePackName: string;
+}): LintOutput;

package/dist/lint.js

@@ -0,0 +1,36 @@
+import { BUILTIN_RULES, runCustomRegex } from "./rules/built-in.js";
+const VERSION = "0.0.1";
+export function lintTicket(ticket, pack, opts) {
+    const checks = [];
+    const ruleConfigs = pack.rules || {};
+    const builtinIds = new Set(BUILTIN_RULES.map((r) => r.id));
+    for (const rule of BUILTIN_RULES) {
+        const cfg = ruleConfigs[rule.id] ?? { enabled: true };
+        if (cfg.enabled === false)
+            continue;
+        checks.push(rule.run(ticket, cfg));
+    }
+    for (const [id, cfg] of Object.entries(ruleConfigs)) {
+        if (builtinIds.has(id))
+            continue;
+        if (cfg.enabled === false)
+            continue;
+        if (cfg.type === "regex") {
+            checks.push(runCustomRegex(ticket, id, cfg));
+        }
+    }
+    const failed = checks.filter((c) => c.status === "fail" && c.severity === "error").length;
+    const warnings = checks.filter((c) => c.status === "fail" && c.severity === "warn").length;
+    const passed = checks.filter((c) => c.status === "pass").length;
+    return {
+        schema_version: "1.0",
+        agent_ready_version: VERSION,
+        ticket_id: ticket.id,
+        adapter: opts.adapter,
+        rule_pack: opts.rulePackName,
+        checked_at: new Date().toISOString(),
+        ready: failed === 0,
+        summary: { passed, failed, warnings },
+        checks
+    };
+}

package/dist/render/markdown.d.ts

@@ -0,0 +1,3 @@
+import type { LintOutput } from "../types.js";
+export declare function renderMarkdown(out: LintOutput): string;
+export declare function renderText(out: LintOutput): string;

package/dist/render/markdown.js

@@ -0,0 +1,28 @@
+export function renderMarkdown(out) {
+    const head = out.ready
+        ? `✓ **${out.ticket_id}** — ready for an agent (${out.summary.passed} checks passed${out.summary.warnings ? `, ${out.summary.warnings} warning(s)` : ""})`
+        : `✗ **${out.ticket_id}** — not ready (${out.summary.failed} blocker(s), ${out.summary.warnings} warning(s))`;
+    const lines = [`### agent-ready check`, "", head, ""];
+    if (out.checks.length) {
+        lines.push("| | Rule | Status |");
+        lines.push("|---|---|---|");
+        for (const c of out.checks) {
+            const icon = c.status === "pass" ? "✓" : c.severity === "warn" ? "⚠" : c.status === "skip" ? "—" : "✗";
+            lines.push(`| ${icon} | \`${c.id}\` | ${c.message}${c.hint ? ` — _${c.hint}_` : ""} |`);
+        }
+    }
+    if (!out.ready) {
+        lines.push("", "**Fix the blockers above before handing this ticket to an AI agent.**");
+    }
+    return lines.join("\n");
+}
+export function renderText(out) {
+    const head = out.ready
+        ? `✓ ${out.ticket_id}  ready  (${out.summary.passed} checks passed${out.summary.warnings ? `, ${out.summary.warnings} warning(s)` : ""})`
+        : `✗ ${out.ticket_id}  not ready  (${out.summary.failed} blocker(s), ${out.summary.warnings} warning(s))`;
+    const rows = out.checks.map((c) => {
+        const icon = c.status === "pass" ? "✓" : c.severity === "warn" ? "⚠" : c.status === "skip" ? "·" : "✗";
+        return `  ${icon} ${c.id.padEnd(28)}  ${c.message}`;
+    });
+    return [head, "", ...rows].join("\n");
+}

package/dist/rules/built-in.d.ts

@@ -0,0 +1,3 @@
+import type { Rule, Ticket, RuleConfig, CheckResult } from "../types.js";
+export declare const BUILTIN_RULES: Rule[];
+export declare function runCustomRegex(ticket: Ticket, id: string, cfg: RuleConfig): CheckResult;

package/dist/rules/built-in.js

@@ -0,0 +1,198 @@
+const AMBIGUOUS_VERBS = [
+    "improve", "optimize", "clean up", "cleanup", "refactor",
+    "enhance", "fix it", "make it better", "tidy", "polish", "modernize"
+];
+const TRIBAL_PHRASES = [
+    "as discussed", "you know what i mean", "the usual way",
+    "like before", "as agreed", "per our chat", "as we talked about"
+];
+const RISK_LABELS = ["risk:low", "risk:medium", "risk:high"];
+const SIZE_LABELS = ["size:s", "size:m", "size:l", "size:xs", "size:xl"];
+function pass(id, severity, message) {
+    return { id, severity, status: "pass", message };
+}
+function fail(id, severity, message, hint) {
+    return { id, severity, status: "fail", message, hint };
+}
+function severityOf(cfg, fallback) {
+    return cfg.severity ?? fallback;
+}
+function bodyLower(t) {
+    return (t.body || "").toLowerCase();
+}
+function labelsLower(t) {
+    return (t.labels || []).map((l) => l.toLowerCase());
+}
+const hasAcceptanceCriteria = {
+    id: "has-acceptance-criteria",
+    defaultSeverity: "error",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const min = cfg.min_count ?? 1;
+        const body = ticket.body || "";
+        const matches = body.match(/^\s*[-*]\s*\[[ x]\]\s+.+$/gm) || [];
+        const numbered = body.match(/^\s*\d+\.\s+.+$/gm) || [];
+        const givenWhenThen = body.match(/given\s+.+\bwhen\b/gi) || [];
+        const total = matches.length + numbered.length + givenWhenThen.length;
+        const headingPresent = /acceptance\s+criteria/i.test(body);
+        if (total >= min || (headingPresent && total > 0)) {
+            return pass(this.id, sev, `Found ${total} acceptance criteria`);
+        }
+        return fail(this.id, sev, `No acceptance criteria found (need at least ${min})`, "Add a checklist, numbered list, or Given/When/Then under an 'Acceptance criteria' heading.");
+    }
+};
+const hasDefinitionOfDone = {
+    id: "has-definition-of-done",
+    defaultSeverity: "warn",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const found = /definition\s+of\s+done|\bdod\b/i.test(ticket.body || "");
+        return found
+            ? pass(this.id, sev, "DoD section found")
+            : fail(this.id, sev, "No Definition of Done found", "Add a 'Definition of Done' section listing test, doc, and review requirements.");
+    }
+};
+const hasRepoTarget = {
+    id: "has-repo-target",
+    defaultSeverity: "error",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const body = ticket.body || "";
+        const inBody = /(^|\n)\s*repo\s*:\s*\S+/i.test(body);
+        const inLabel = labelsLower(ticket).some((l) => l.startsWith("repo:"));
+        if (inBody || inLabel)
+            return pass(this.id, sev, "Target repo specified");
+        return fail(this.id, sev, "Ticket does not specify the target repo", "Add `repo: owner/name` to the body or a `repo:<name>` label.");
+    }
+};
+const hasRiskClassification = {
+    id: "has-risk-classification",
+    defaultSeverity: "error",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const found = labelsLower(ticket).some((l) => RISK_LABELS.includes(l));
+        return found
+            ? pass(this.id, sev, "Risk classification label found")
+            : fail(this.id, sev, "No risk classification label", "Add one of: risk:low, risk:medium, risk:high");
+    }
+};
+const hasTestExpectations = {
+    id: "has-test-expectations",
+    defaultSeverity: "warn",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const body = bodyLower(ticket);
+        const found = /how to verify|test plan|playwright|jest|pytest|unit test|e2e/i.test(body);
+        return found
+            ? pass(this.id, sev, "Test expectations described")
+            : fail(this.id, sev, "No test expectations described", "Add a 'How to verify' or 'Test plan' section.");
+    }
+};
+const noAmbiguousVerbs = {
+    id: "no-ambiguous-verbs",
+    defaultSeverity: "warn",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const extras = (cfg.extra_terms || []).map((s) => s.toLowerCase());
+        const all = [...AMBIGUOUS_VERBS, ...extras];
+        const haystack = `${ticket.title} ${ticket.body}`.toLowerCase();
+        const hits = all.filter((v) => new RegExp(`\\b${v}\\b`, "i").test(haystack));
+        return hits.length === 0
+            ? pass(this.id, sev, "No ambiguous verbs")
+            : fail(this.id, sev, `Ambiguous verb(s): ${hits.join(", ")}`, "Prefer concrete verbs like 'add', 'fix', 'remove', 'replace'.");
+    }
+};
+const bodyMinLength = {
+    id: "body-min-length",
+    defaultSeverity: "error",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const min = cfg.min_count ?? 100;
+        const len = (ticket.body || "").trim().length;
+        return len >= min
+            ? pass(this.id, sev, `Body length ${len} >= ${min}`)
+            : fail(this.id, sev, `Body too short: ${len} chars (need >= ${min})`, "Expand the description with context, AC, and test plan.");
+    }
+};
+const noTribalKnowledge = {
+    id: "no-tribal-knowledge",
+    defaultSeverity: "warn",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const body = bodyLower(ticket);
+        const hits = TRIBAL_PHRASES.filter((p) => body.includes(p));
+        return hits.length === 0
+            ? pass(this.id, sev, "No tribal-knowledge phrases")
+            : fail(this.id, sev, `Tribal-knowledge phrase(s): ${hits.join("; ")}`, "Replace with explicit detail. The agent has no prior chat context.");
+    }
+};
+const tShirtSizePresent = {
+    id: "t-shirt-size-present",
+    defaultSeverity: "warn",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const body = ticket.body || "";
+        const inBody = /(^|\n)\s*size\s*:\s*(xs|s|m|l|xl)\b/i.test(body);
+        const inLabel = labelsLower(ticket).some((l) => SIZE_LABELS.includes(l));
+        if (inBody || inLabel)
+            return pass(this.id, sev, "T-shirt size present");
+        return fail(this.id, sev, "No t-shirt size estimate", "Add `size: S|M|L|XL` to the body or a `size:<x>` label.");
+    }
+};
+const hasDesignLink = {
+    id: "has-design-link",
+    defaultSeverity: "warn",
+    run(ticket, cfg) {
+        const sev = severityOf(cfg, this.defaultSeverity);
+        const triggerLabels = (cfg.labels || ["ui", "ux", "frontend"]).map((s) => s.toLowerCase());
+        const ticketLabels = labelsLower(ticket);
+        const triggered = triggerLabels.some((l) => ticketLabels.includes(l));
+        if (!triggered)
+            return { id: this.id, severity: sev, status: "skip", message: "Not a UI ticket" };
+        const body = ticket.body || "";
+        const found = /figma\.com|ardoq\.com|miro\.com|excalidraw\.com/i.test(body);
+        return found
+            ? pass(this.id, sev, "Design link found")
+            : fail(this.id, sev, "UI ticket has no design link", "Link to the Figma/Ardoq/Miro source of truth.");
+    }
+};
+export const BUILTIN_RULES = [
+    hasAcceptanceCriteria,
+    hasDefinitionOfDone,
+    hasRepoTarget,
+    hasRiskClassification,
+    hasTestExpectations,
+    noAmbiguousVerbs,
+    bodyMinLength,
+    noTribalKnowledge,
+    tShirtSizePresent,
+    hasDesignLink
+];
+export function runCustomRegex(ticket, id, cfg) {
+    const sev = cfg.severity ?? "error";
+    if (!cfg.pattern || !cfg.field) {
+        return fail(id, sev, "Invalid custom rule (missing pattern or field)");
+    }
+    const re = new RegExp(cfg.pattern, cfg.flags ?? "i");
+    let haystack = "";
+    switch (cfg.field) {
+        case "title":
+            haystack = ticket.title || "";
+            break;
+        case "body":
+            haystack = ticket.body || "";
+            break;
+        case "labels":
+            haystack = (ticket.labels || []).join(" ");
+            break;
+        case "any":
+            haystack = `${ticket.title || ""} ${ticket.body || ""} ${(ticket.labels || []).join(" ")}`;
+            break;
+    }
+    const matched = re.test(haystack);
+    const want = cfg.must_match !== false;
+    const ok = matched === want;
+    return ok
+        ? pass(id, sev, cfg.message || `Custom regex passed (${cfg.field})`)
+        : fail(id, sev, cfg.message || `Custom regex failed (${cfg.field})`);
+}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export type Severity = "error" | "warn" | "info";
+export interface Ticket {
+    id: string;
+    title: string;
+    body: string;
+    labels: string[];
+    url?: string;
+}
+export interface RuleConfig {
+    enabled?: boolean;
+    severity?: Severity;
+    min_count?: number;
+    extra_terms?: string[];
+    labels?: string[];
+    type?: "regex";
+    pattern?: string;
+    flags?: string;
+    field?: "title" | "body" | "labels" | "any";
+    must_match?: boolean;
+    message?: string;
+}
+export interface RulePack {
+    version: 1;
+    extends?: string;
+    rules: Record<string, RuleConfig>;
+}
+export interface CheckResult {
+    id: string;
+    severity: Severity;
+    status: "pass" | "fail" | "skip";
+    message: string;
+    hint?: string;
+}
+export interface LintOutput {
+    schema_version: "1.0";
+    agent_ready_version: string;
+    ticket_id: string;
+    adapter: string;
+    rule_pack: string;
+    checked_at: string;
+    ready: boolean;
+    summary: {
+        passed: number;
+        failed: number;
+        warnings: number;
+    };
+    checks: CheckResult[];
+}
+export interface Rule {
+    id: string;
+    defaultSeverity: Severity;
+    run(ticket: Ticket, config: RuleConfig): CheckResult;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@syedshoaib/agent-ready",
+  "version": "0.0.2",
+  "description": "Make every ticket ready for AI coding agents — a Definition-of-Ready linter.",
+  "type": "module",
+  "bin": {
+    "agent-ready": "dist/cli.js",
+    "story-lint": "dist/cli.js"
+  },
+  "main": "dist/lint.js",
+  "types": "dist/lint.d.ts",
+  "files": [
+    "dist",
+    "rule-packs",
+    "schema",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "check:bad": "node dist/cli.js check examples/tickets/bad-ticket.json",
+    "check:good": "node dist/cli.js check examples/tickets/good-ticket.json",
+    "test": "node --test test/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "sdlc",
+    "linter",
+    "definition-of-ready",
+    "jira",
+    "github-issues",
+    "copilot",
+    "claude-code",
+    "cursor"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Schoaib/agent-ready.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Schoaib/agent-ready/issues"
+  },
+  "homepage": "https://github.com/Schoaib/agent-ready#readme"
+}

package/rule-packs/default.yaml

@@ -0,0 +1,50 @@
+# agent-ready default rule pack
+# Loaded automatically when no --rules flag is passed.
+# Override per-rule by writing your own .agent-ready/rules.yaml with `extends: default`.
+
+version: 1
+
+rules:
+  has-acceptance-criteria:
+    enabled: true
+    min_count: 1
+    severity: error
+
+  has-definition-of-done:
+    enabled: true
+    severity: warn
+
+  has-repo-target:
+    enabled: true
+    severity: error
+
+  has-risk-classification:
+    enabled: true
+    severity: error
+
+  has-test-expectations:
+    enabled: true
+    severity: warn
+
+  no-ambiguous-verbs:
+    enabled: true
+    severity: warn
+    extra_terms: []
+
+  body-min-length:
+    enabled: true
+    min_count: 100
+    severity: error
+
+  no-tribal-knowledge:
+    enabled: true
+    severity: warn
+
+  t-shirt-size-present:
+    enabled: true
+    severity: warn
+
+  has-design-link:
+    enabled: true
+    severity: warn
+    labels: [ui, ux, frontend]

package/schema/output.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-ready.dev/schema/output.v1.json",
+  "title": "agent-ready CLI output",
+  "description": "Machine-readable result of an agent-ready check. Stable across versions; safe to consume in CI and downstream tools (e.g. Gatepack).",
+  "type": "object",
+  "required": ["schema_version", "ticket_id", "ready", "checks", "summary"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0" },
+    "agent_ready_version": { "type": "string" },
+    "ticket_id": { "type": "string" },
+    "adapter": { "type": "string", "enum": ["file", "github", "jira", "linear"] },
+    "rule_pack": { "type": "string" },
+    "checked_at": { "type": "string", "format": "date-time" },
+    "ready": {
+      "type": "boolean",
+      "description": "True iff zero error-severity rules failed."
+    },
+    "summary": {
+      "type": "object",
+      "required": ["passed", "failed", "warnings"],
+      "properties": {
+        "passed": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 },
+        "warnings": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "status", "message"],
+        "properties": {
+          "id": { "type": "string" },
+          "severity": { "type": "string", "enum": ["error", "warn", "info"] },
+          "status": { "type": "string", "enum": ["pass", "fail", "skip"] },
+          "message": { "type": "string" },
+          "hint": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schema/rule-pack.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-ready.dev/schema/rule-pack.v1.json",
+  "title": "agent-ready rule pack",
+  "description": "Declarative ruleset describing what makes a ticket 'ready' for an AI coding agent.",
+  "type": "object",
+  "required": ["version"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Rule pack schema version."
+    },
+    "extends": {
+      "type": "string",
+      "description": "Name of a built-in pack to inherit from (e.g. 'default', 'strict'). Local overrides win."
+    },
+    "rules": {
+      "type": "object",
+      "description": "Map of rule-id -> rule configuration. Rule ids match built-in rule names, or define a 'type' for custom rules.",
+      "additionalProperties": {
+        "oneOf": [
+          { "$ref": "#/$defs/builtinRuleConfig" },
+          { "$ref": "#/$defs/customRegexRule" }
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "severity": {
+      "type": "string",
+      "enum": ["error", "warn", "info"],
+      "default": "error"
+    },
+    "builtinRuleConfig": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "severity": { "$ref": "#/$defs/severity" },
+        "min_count": { "type": "integer", "minimum": 1 },
+        "extra_terms": { "type": "array", "items": { "type": "string" } },
+        "labels": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "customRegexRule": {
+      "type": "object",
+      "required": ["type", "pattern", "field"],
+      "properties": {
+        "type": { "const": "regex" },
+        "pattern": { "type": "string", "description": "JavaScript regex pattern." },
+        "flags": { "type": "string", "default": "i" },
+        "field": {
+          "type": "string",
+          "enum": ["title", "body", "labels", "any"],
+          "description": "Where to apply the pattern."
+        },
+        "must_match": { "type": "boolean", "default": true },
+        "severity": { "$ref": "#/$defs/severity" },
+        "message": { "type": "string" }
+      }
+    }
+  }
+}