agent-threader 2.0.5

package/site/style.css

@@ -0,0 +1,319 @@
+*,
+*::before,
+*::after {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+:root {
+  --bg: #0a0e17;
+  --surface: #111827;
+  --surface-hover: #1a2332;
+  --border: #1e293b;
+  --text: #e2e8f0;
+  --text-dim: #94a3b8;
+  --accent: #38bdf8;
+  --accent-hover: #7dd3fc;
+  --success: #34d399;
+  --red: #f87171;
+  --yellow: #fbbf24;
+  --green: #4ade80;
+  --font-sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --font-mono: "JetBrains Mono", "Fira Code", "Cascadia Code", monospace;
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  font-family: var(--font-sans);
+  background: var(--bg);
+  color: var(--text);
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+}
+
+.container {
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 0 1.5rem;
+}
+
+.hero {
+  padding: 6rem 0 5rem;
+  text-align: center;
+  background: linear-gradient(180deg, #0f1729 0%, var(--bg) 100%);
+}
+
+.logo {
+  font-size: 3.5rem;
+  font-weight: 800;
+  letter-spacing: -0.03em;
+  color: var(--text);
+}
+
+.logo .accent {
+  color: var(--accent);
+}
+
+.tagline {
+  font-size: 1.25rem;
+  color: var(--text-dim);
+  margin-top: 0.75rem;
+  font-weight: 400;
+}
+
+.subtitle {
+  font-size: 1rem;
+  color: var(--text-dim);
+  margin-top: 0.25rem;
+  opacity: 0.7;
+}
+
+.cta-row {
+  margin-top: 2.5rem;
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+  flex-wrap: wrap;
+}
+
+.btn {
+  display: inline-block;
+  padding: 0.75rem 2rem;
+  border-radius: 8px;
+  font-size: 0.95rem;
+  font-weight: 600;
+  text-decoration: none;
+  transition: all 0.2s ease;
+}
+
+.btn-primary {
+  background: var(--accent);
+  color: var(--bg);
+}
+
+.btn-primary:hover {
+  background: var(--accent-hover);
+  transform: translateY(-1px);
+}
+
+.btn-secondary {
+  background: transparent;
+  color: var(--accent);
+  border: 1px solid var(--border);
+}
+
+.btn-secondary:hover {
+  border-color: var(--accent);
+  background: rgba(56, 189, 248, 0.05);
+}
+
+.features,
+.contracts,
+.cli-section,
+.install-section {
+  padding: 5rem 0;
+}
+
+.features h2,
+.contracts h2,
+.cli-section h2,
+.install-section h2 {
+  font-size: 2rem;
+  font-weight: 700;
+  text-align: center;
+  margin-bottom: 3rem;
+  letter-spacing: -0.02em;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 1.5rem;
+}
+
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 2rem 1.5rem;
+  transition: border-color 0.2s ease, transform 0.2s ease;
+}
+
+.card:hover {
+  border-color: var(--accent);
+  transform: translateY(-2px);
+}
+
+.card-icon {
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: 50%;
+  background: rgba(56, 189, 248, 0.1);
+  color: var(--accent);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 1.1rem;
+  margin-bottom: 1rem;
+}
+
+.card h3 {
+  font-size: 1.1rem;
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}
+
+.card p {
+  font-size: 0.9rem;
+  color: var(--text-dim);
+  line-height: 1.5;
+}
+
+.card code,
+.install-note code {
+  font-family: var(--font-mono);
+  font-size: 0.85em;
+  background: rgba(56, 189, 248, 0.1);
+  padding: 0.1em 0.35em;
+  border-radius: 4px;
+  color: var(--accent);
+}
+
+.contracts {
+  background: var(--surface);
+  border-top: 1px solid var(--border);
+  border-bottom: 1px solid var(--border);
+}
+
+.contract-grid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  justify-content: center;
+}
+
+.contract-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.4rem;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 1.25rem 1.5rem;
+  min-width: 160px;
+}
+
+.contract-item code {
+  font-family: var(--font-mono);
+  font-size: 0.9rem;
+  color: var(--accent);
+  font-weight: 600;
+}
+
+.contract-item span {
+  font-size: 0.8rem;
+  color: var(--text-dim);
+}
+
+.terminal {
+  background: #0d1117;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  overflow: hidden;
+  max-width: 760px;
+  margin: 0 auto;
+}
+
+.terminal-bar {
+  display: flex;
+  gap: 6px;
+  padding: 12px 16px;
+  background: #161b22;
+  border-bottom: 1px solid var(--border);
+}
+
+.dot {
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+}
+
+.dot.red { background: var(--red); }
+.dot.yellow { background: var(--yellow); }
+.dot.green { background: var(--green); }
+
+.terminal pre {
+  padding: 1.5rem;
+  overflow-x: auto;
+}
+
+.terminal code {
+  font-family: var(--font-mono);
+  font-size: 0.85rem;
+  line-height: 1.7;
+  color: var(--text);
+}
+
+.terminal .prompt { color: var(--accent); font-weight: 700; }
+.terminal .success { color: var(--success); }
+.terminal .dim { color: var(--text-dim); }
+.terminal .bold { color: var(--text); font-weight: 700; }
+
+.install-note {
+  text-align: center;
+  color: var(--text-dim);
+  font-size: 0.9rem;
+  margin-top: 1.5rem;
+}
+
+.install-links {
+  margin-top: 1rem;
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+  flex-wrap: wrap;
+}
+
+.text-link {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+.text-link:hover,
+footer a:hover {
+  text-decoration: underline;
+}
+
+footer {
+  padding: 3rem 0;
+  border-top: 1px solid var(--border);
+  text-align: center;
+}
+
+footer p {
+  color: var(--text-dim);
+  font-size: 0.85rem;
+}
+
+footer a {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+@media (max-width: 640px) {
+  .logo { font-size: 2.5rem; }
+  .tagline { font-size: 1.05rem; }
+  .features h2,
+  .contracts h2,
+  .cli-section h2,
+  .install-section h2 { font-size: 1.6rem; }
+  .grid { grid-template-columns: 1fr; }
+  .contract-grid { flex-direction: column; align-items: center; }
+  .hero { padding: 4rem 0 3rem; }
+}

package/skill/SKILL.md

@@ -0,0 +1,127 @@
+---
+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 Summary
+
+The v2 system has five moving parts:
+
+1. **Manifest** — declares work items, dependencies, timeouts, and verification profiles
+2. **Orchestrator** — owns scheduling, parsing, verification, checkpointing, healing, and retry policy
+3. **Adapters** — CLI-specific execution layers (`agent`, `opencode`, `claude`) that the orchestrator calls through a uniform interface
+4. **Worker** — the model invocation that performs task work and emits a `task_result.v2` JSON contract
+5. **Healer** — the model invocation that diagnoses fixable failures and emits a `heal_decision.v2` JSON contract
+
+The default healing strategy is **Progressive Batch Healing (PBH)**: start with small batches, grow when stable, shrink when unstable, escalate when stuck.
+
+## Normative Specification
+
+The full architecture, contracts, schemas, and behavioral rules are defined in `SPEC.md` in this directory. That document is the single source of truth.
+
+Read `SPEC.md` when you need:
+
+- the end-to-end control flow
+- JSON schemas for manifest, worker result, healer decision, and state
+- PBH scheduling rules and defaults
+- verification and write-safety model
+- adapter interface contract
+- failure classification, signature generation, and convergence rules
+- resume and reconciliation semantics
+
+## Canonical Source Of Truth
+
+Use these directories with clear ownership boundaries:
+
+- `SPEC.md` — normative behavior and runtime rules
+- `schemas/` — machine-readable contract authority
+- `templates/` — shared parser, types, and runtime scaffolding
+- `platforms/` — thin translation layers for Codex, Cursor, Claude, and Windsurf
+
+The orchestrator core should stay platform-neutral. Platform packaging may change invocation syntax and workspace UX, but not contracts or state semantics.
+
+## Schemas
+
+Machine-readable JSON schemas live in `schemas/`:
+
+- `manifest.v2.json`
+- `verify_profile.v2.json`
+- `task_result.v2.json`
+- `heal_decision.v2.json`
+- `state.v2.json`
+
+## Templates
+
+Reference implementation skeletons live in `templates/`:
+
+- `types.ts` — TypeScript type definitions for all contracts and the adapter interface
+- `parser.ts` — shared parser and validator utilities (sentinel extraction, JSON repair, schema validation)
+- `orchestrator.ts` — shared runtime utilities for atomic state writes and stable failure signatures
+
+## Self-Healing: Model Selection Rule
+
+When the user requests a self-healing runner, ask which models to use before generating code:
+
+- **Worker CLI and model** — runs the inner loop (can be fast/cheap)
+- **Healer CLI and model** — runs the outer diagnosis loop (should be more capable)
+
+If the user does not specify, state the defaults explicitly before proceeding:
+
+- Worker: the CLI the user is already using, default model
+- Healer: same CLI family, stronger model tier
+
+## Platform Wrappers
+
+Platform-specific wrappers live in `platforms/`. They are thin routing layers only.
+
+- `platforms/windsurf/` — Windsurf workflow
+- `platforms/cursor/` — Cursor rule + skill pointer
+- `platforms/codex/` — Codex agent registration
+- `platforms/claude/` — Claude command
+
+Platform wrappers MUST NOT redefine architecture, contracts, or healing policy.
+
+## Portability Rule
+
+Platform wrappers may adapt:
+
+- invocation command and flags
+- prompt transport (`stdin`, argument, or PTY)
+- approval handling and setup notes
+
+Platform wrappers MUST preserve:
+
+- contract field names and sentinel strings
+- parser behavior
+- PBH defaults and convergence rules
+- state transitions and resume semantics
+
+## Workflow
+
+1. Define the unit of work (component, story, work package, ticket, file).
+2. Create the manifest (`manifest.v2` JSON).
+3. Write shared context and per-task prompts.
+4. Define the completion contract in the prompt (instruct the worker to emit `<<<TASK_RESULT_V2>>>`).
+5. Choose the CLI adapter (`agent`, `opencode`, `claude`).
+6. Build the orchestrator (use `templates/` as starting point).
+7. Run sequential first, add concurrency after contracts and parsing are stable.
+8. Add verification gates (build, test, lint, smoke).
+9. Add healing only after the base loop works (`--heal auto`).
+10. Resume with `--resume` after interruptions.