agent-threader 2.0.5

package/skill/schemas/manifest.v2.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "manifest.v2.json",
+  "title": "AgentThreader Manifest v2",
+  "description": "Declares the set of tasks, their dependencies, timeouts, and verification profiles for a runner invocation.",
+  "type": "object",
+  "required": ["manifest_version", "run_id", "tasks"],
+  "properties": {
+    "manifest_version": {
+      "type": "string",
+      "const": "2.0",
+      "description": "Contract version. MUST be \"2.0\"."
+    },
+    "run_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Logical run identifier."
+    },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/task" },
+      "description": "Ordered list of task definitions."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "task": {
+      "type": "object",
+      "required": ["id", "prompt_ref", "depends_on", "timeout_sec", "verify_profile"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable, unique task identifier."
+        },
+        "prompt_ref": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Relative path or logical reference to the task prompt."
+        },
+        "depends_on": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Upstream task IDs that must be DONE before execution."
+        },
+        "timeout_sec": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Task timeout in seconds."
+        },
+        "verify_profile": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Name of the project-defined verification profile."
+        },
+        "context_refs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Shared context references applied to the task."
+        },
+        "priority": {
+          "type": "number",
+          "description": "Lower number means earlier scheduling within the same dependency depth."
+        },
+        "retry_policy": { "$ref": "#/$defs/retry_policy" },
+        "metadata": {
+          "type": "object",
+          "description": "Arbitrary task metadata for reporting or filtering."
+        }
+      },
+      "additionalProperties": false
+    },
+    "retry_policy": {
+      "type": "object",
+      "properties": {
+        "max_attempts": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Maximum worker attempts for this task. Defaults to global policy if omitted."
+        },
+        "retry_on": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Failure classes eligible for retry."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/skill/schemas/state.v2.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "state.v2.json",
+  "title": "Run State v2",
+  "description": "Persistent orchestrator state for resume, convergence tracking, and reporting.",
+  "type": "object",
+  "required": ["state_version", "run_id", "run_status", "abort_reason", "manifest_digest", "policy", "tasks", "healing_rounds"],
+  "properties": {
+    "state_version": {
+      "type": "string",
+      "const": "2.0"
+    },
+    "run_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "run_status": {
+      "type": "string",
+      "enum": ["RUNNING", "COMPLETED", "ABORTED"]
+    },
+    "abort_reason": {
+      "type": ["string", "null"],
+      "description": "Human-readable abort reason when run_status is ABORTED."
+    },
+    "manifest_digest": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Hash of the normalized manifest used for resume validation."
+    },
+    "policy": { "$ref": "#/$defs/policy" },
+    "tasks": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/task_state" },
+      "description": "Per-task state keyed by task ID."
+    },
+    "healing_rounds": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/healing_round" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "policy": {
+      "type": "object",
+      "required": [
+        "heal_schedule",
+        "batch_strategy",
+        "current_batch_size",
+        "failure_threshold",
+        "max_worker_attempts_per_task",
+        "max_heal_rounds_per_window",
+        "max_total_heal_rounds",
+        "signature_repeat_limit"
+      ],
+      "properties": {
+        "heal_schedule": {
+          "type": "string",
+          "enum": ["auto", "off", "task", "batch", "epoch"]
+        },
+        "batch_strategy": {
+          "type": "string",
+          "enum": ["fibonacci", "fixed"]
+        },
+        "current_batch_size": {
+          "type": "number",
+          "minimum": 1
+        },
+        "failure_threshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "max_worker_attempts_per_task": {
+          "type": "number",
+          "minimum": 1
+        },
+        "max_heal_rounds_per_window": {
+          "type": "number",
+          "minimum": 0
+        },
+        "max_total_heal_rounds": {
+          "type": "number",
+          "minimum": 0
+        },
+        "signature_repeat_limit": {
+          "type": "number",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "task_state": {
+      "type": "object",
+      "required": [
+        "status",
+        "worker_attempts",
+        "healer_attempts",
+        "last_failure_class",
+        "last_failure_signature",
+        "applied_patch_ids",
+        "history"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["PENDING", "RUNNING", "DONE", "BLOCKED", "FAILED", "ESCALATED"]
+        },
+        "worker_attempts": { "type": "number", "minimum": 0 },
+        "healer_attempts": { "type": "number", "minimum": 0 },
+        "last_failure_class": { "type": ["string", "null"] },
+        "last_failure_signature": { "type": ["string", "null"] },
+        "applied_patch_ids": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "history": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/history_entry" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "history_entry": {
+      "type": "object",
+      "required": ["task_id", "phase", "attempt_number", "log_path", "timestamp"],
+      "properties": {
+        "task_id": { "type": "string" },
+        "phase": {
+          "type": "string",
+          "enum": ["worker", "verify", "healer", "rollback"]
+        },
+        "attempt_number": { "type": "number", "minimum": 1 },
+        "log_path": { "type": "string" },
+        "verify_log_path": { "type": ["string", "null"] },
+        "exit_code": { "type": ["number", "null"] },
+        "failure_class": { "type": ["string", "null"] },
+        "failure_signature": { "type": ["string", "null"] },
+        "applied_patch_ids": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "duration_sec": { "type": ["number", "null"] },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "additionalProperties": false
+    },
+    "healing_round": {
+      "type": "object",
+      "required": ["round_number", "scope", "window_task_ids", "failed_task_ids", "decision", "applied_patch_ids", "timestamp"],
+      "properties": {
+        "round_number": { "type": "number", "minimum": 1 },
+        "scope": {
+          "type": "string",
+          "enum": ["task", "batch", "epoch"]
+        },
+        "window_task_ids": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "failed_task_ids": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "decision": {
+          "type": "string",
+          "enum": ["RETRY", "ESCALATE", "NOT_FIXABLE"]
+        },
+        "applied_patch_ids": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/skill/schemas/task_result.v2.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "task_result.v2.json",
+  "title": "Task Result v2",
+  "description": "Worker output contract. Emitted inside <<<TASK_RESULT_V2>>> fences.",
+  "type": "object",
+  "required": ["contract_version", "task_id", "status", "summary"],
+  "properties": {
+    "contract_version": {
+      "type": "string",
+      "const": "2.0"
+    },
+    "task_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Task ID matching the current manifest task."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["DONE", "BLOCKED", "FAILED", "CONTRACT_ERROR"],
+      "description": "Worker-declared outcome."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Short human-readable summary of what happened."
+    },
+    "changed_files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Relative file paths changed by the proposed work."
+    },
+    "writes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/write_entry" },
+      "description": "Proposed file write operations applied by the orchestrator."
+    },
+    "evidence": { "$ref": "#/$defs/evidence" },
+    "failure_class": {
+      "type": "string",
+      "description": "Optional worker-supplied hint. The orchestrator still owns final classification."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "write_entry": {
+      "type": "object",
+      "required": ["path", "op", "encoding"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Relative normalized path. MUST NOT escape the workspace root."
+        },
+        "op": {
+          "type": "string",
+          "enum": ["create", "replace", "append"]
+        },
+        "encoding": {
+          "type": "string",
+          "const": "utf8"
+        },
+        "content": {
+          "type": "string",
+          "description": "Inline file content to be applied by the orchestrator."
+        },
+        "content_ref": {
+          "type": "string",
+          "description": "Path to staged content written by the worker tooling instead of inline content."
+        },
+        "sha256_before": {
+          "type": "string",
+          "description": "Optional precondition hash for conflict detection."
+        }
+      },
+      "additionalProperties": false,
+      "anyOf": [
+        { "required": ["content"] },
+        { "required": ["content_ref"] }
+      ]
+    },
+    "evidence": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Commands the worker claims to have run."
+        },
+        "log_refs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative log references produced by the worker."
+        },
+        "notes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Additional structured evidence notes."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/skill/schemas/verify_profile.v2.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "verify_profile.v2.json",
+  "title": "AgentThreader v2 Verification Profile Registry",
+  "description": "Operator-defined verification profiles resolved by the orchestrator.",
+  "type": "object",
+  "required": ["profiles"],
+  "additionalProperties": false,
+  "properties": {
+    "profiles": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/profile" },
+      "description": "Profile definitions keyed by profile name."
+    }
+  },
+  "$defs": {
+    "profile": {
+      "type": "object",
+      "required": ["steps"],
+      "additionalProperties": false,
+      "properties": {
+        "steps": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/step" },
+          "minItems": 1
+        },
+        "rollback_on_failure": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether to rollback applied writes when any verification step fails."
+        }
+      }
+    },
+    "step": {
+      "type": "object",
+      "required": ["name", "cmd"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable step name for logging."
+        },
+        "cmd": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Shell command to execute."
+        },
+        "cwd": {
+          "type": "string",
+          "description": "Working directory for the command. Defaults to workspace root."
+        },
+        "timeout_sec": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Step timeout in seconds."
+        }
+      }
+    }
+  }
+}

package/skill/skills/agent-threader/agent-threader.md

@@ -0,0 +1,85 @@
+---
+name: agent-threader
+version: "2.0"
+description: "AgentThreader -- build or review manifest-driven agentic CLI orchestration with structured JSON contracts, schema-validated parsing, resumable state, dependency-aware scheduling, bounded self-healing, and orchestrator-owned verification."
+---
+
+# AgentThreader
+
+## When To Use This Skill
+
+Use this skill when manual chat execution no longer scales and the right answer is a repeatable runner around an agentic CLI.
+
+Matching requests include:
+
+- batch prompt runners over tasks, manifests, components, stories, or tickets
+- looping an agentic CLI (`agent`, `opencode`, `claude`) across many items
+- resumable or checkpointed agent loops with per-task logs
+- self-healing outer loops that diagnose failures and patch prompts
+- overnight or unattended batch runs with verification gates
+- stage-based workflows where items pass through multiple prompt phases
+- log triage followed by targeted recheck runs
+
+## Architecture
+
+{{include:domain/architecture-overview.md}}
+
+---
+
+## Contracts
+
+{{include:domain/contracts.md}}
+
+---
+
+## Healing Model
+
+{{include:domain/pbh-healing.md}}
+
+---
+
+## Verification and Safety
+
+{{include:domain/verification-safety.md}}
+
+---
+
+## Adapter Model
+
+{{include:domain/adapter-model.md}}
+
+---
+
+## State and Resume
+
+{{include:domain/state-resume.md}}
+
+---
+
+## Normative Specification
+
+The full architecture, contracts, schemas, and behavioral rules are defined in `SPEC.md`. That document is the single source of truth. Read it when you need the end-to-end control flow, complete schema field definitions, or edge-case behavioral rules.
+
+## Canonical Source Of Truth
+
+{{include:meta/schemas-reference.md}}
+
+{{include:meta/templates-reference.md}}
+
+---
+
+## Model Selection
+
+{{include:common/model-selection.md}}
+
+---
+
+## Portability
+
+{{include:common/portability-rules.md}}
+
+---
+
+## Workflow
+
+{{include:common/workflow.md}}

package/skill/templates/orchestrator.ts

@@ -0,0 +1,38 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+interface AtomicWriteOptions {
+  filePath: string;
+  value: unknown;
+}
+
+export async function writeAtomicJson(options: AtomicWriteOptions): Promise<void> {
+  const dir = path.dirname(options.filePath);
+  const base = path.basename(options.filePath);
+  const tmpPath = path.join(dir, `.${base}.tmp`);
+
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(tmpPath, `${JSON.stringify(options.value, null, 2)}\n`, "utf8");
+  await fs.rename(tmpPath, options.filePath);
+}
+
+export function stableFailureSignature(failureClass: string, primarySignal: string): string {
+  const cleaned = primarySignal
+    .toLowerCase()
+    .replace(/\b\d{4}-\d{2}-\d{2}[t\s]\d{2}:\d{2}:\d{2}(?:\.\d+)?z?\b/g, "")
+    .replace(/\/[^\s]+/g, "")
+    .replace(/\b\d+\b/g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 120)
+    .replace(/\s+/g, "_");
+
+  return `${failureClass.toLowerCase()}:${cleaned || "unknown"}`;
+}
+
+export function shouldEscalateRepeatedSignature(
+  repeatCount: number,
+  signatureRepeatLimit: number,
+): boolean {
+  return repeatCount >= signatureRepeatLimit;
+}