diff --git a/.gitignore b/.gitignore index 43c0e378..0719fddc 100644 --- a/.gitignore +++ b/.gitignore @@ -70,3 +70,7 @@ tests/ # reviewer's feedback and belongs next to the artifact in git. *.review.html .human-gate/ + +# agent-launcher user output folders (goal.json, payloads, launch.sh live here) +my-agent/ +my-agent-*/ diff --git a/CHANGELOG.md b/CHANGELOG.md index ab6acdd4..10a5889d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,52 @@ All notable changes to the Claude Skills Library will be documented in this file The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] — agent-launcher: session-goal domain plugin for Claude Managed Agents (PR #961, merged 2026-08-21) + +### Added — `agent-launcher/` (new top-level domain, 19th) + +Plugin re-implementation of Anthropic's +[`launch-your-agent`](https://github.com/anthropics/launch-your-agent) reference +skill (Apache-2.0; **independent, not a fork**) for building **Claude Managed +Agents (CMA)** in the user's own Anthropic account. Organizing idea: **every +session starts with a goal** (`./my-agent/goal.json`, surfaced by an opt-in +`AGENT_LAUNCHER_SESSION=1` SessionStart hook and driven by `/cs:goal`); +`loop_compiler.py` compiles that goal into a **bounded grade→iterate loop** +(CMA `user.define_outcome` self-grading, `max_iterations` clamped 1..20 — never +unbounded), a **recurring POSIX-cron scheduled-deployment loop** ("run without +you", optionally self-grading each firing via a nested outcome), or a +**single-pass interview→stage→launch workflow**. + +- **6 skills:** `agent-launcher-orchestrator` (`context: fork` goal router with + exit-code route/ask/refuse) + `interview` (six intake slots → build sheet with + primitives table + v1/v2 deferrals + eval plan) + `stage-launch` (validated + env/agent/session/kickoff payloads + resumable **BYOK curl** launch script + that reads `$ANTHROPIC_API_KEY` at runtime and never embeds it) + + `grade-iterate` (outcome/rubric + verdict reader + held-back eval scaffold + capped at the 25-thread ceiling) + `run-without-you` (5-field POSIX cron + + IANA tz + wall-clock-DST validation, deployment payload with test-run curl, + NEXT-DIRECTIONS writer) + `wrap-up` (primitives inventory + regenerated + single-file overview HTML + ranked next upgrades). +- **18 stdlib-only deterministic scaffolder tools** (3 per skill; NO network/API + calls; all pass `--help` + `--sample`), **4 agents** (orchestrator + + interviewer + grader + deployer), **8 `/cs:*` commands** (launch, goal, + interview, stage-launch, grade, run-without-you, wrap-up, + grill-agent-launcher), **opt-in SessionStart/SessionEnd hooks** (exit 0 on any + error — can never break a session), **5 shared references**, **4 assets** + (build-sheet JSON schema + overview/NEXT-DIRECTIONS templates + example). +- Validators enforce CMA limits (≤20 skills/session, ≤8 memory stores, depth-1 + multiagent ≤20 roster / ≤25 threads, `max_iterations` ≤20, ≤20 creds/vault, + ≤1,000 deployments/org); `payload_validator.py` FAILs on any embedded API key. +- **Verification:** independent 10-agent workflow re-checked every SPEC.md part + against disk — 9/9 PASS, zero differences from spec (recorded in + `agent-launcher/DELIVERY-REPORT.md`). Full 4-phase pipeline verified + end-to-end; generated `launch.sh` passes `bash -n`. +- **Counters** (at merge): skills 362 → 368, domains 18 → 19, tools 644 → 664, + refs 741 → 746, agents 102 → 106, commands 116 → 124, plugins 88 → 89 + (derived via `scripts/derive_counters.py --check`). +- Distinct from `engineering/agent-harness` (generic bounded loop over any repo + domain) and `engineering/write-a-skill` (authors Claude Code skills, not CMAs). + ## [Unreleased] — human-gate: batched human review as a verification artifact (this PR) ### Audited — `petergyang/human-review` diff --git a/agent-launcher/PUBLISH-CLAWHUB.md b/agent-launcher/PUBLISH-CLAWHUB.md new file mode 100644 index 00000000..42dfc727 --- /dev/null +++ b/agent-launcher/PUBLISH-CLAWHUB.md @@ -0,0 +1,43 @@ +# ClawHub publish plan — agent-launcher (6 skills) + +Prepared 2026-08-24. Live publish requires the maintainer's ClawHub credentials + +drip timer, which do not exist in remote sessions — run this from the maintainer +machine. + +## What to publish + +Six skills from `agent-launcher/skills/`, version **2.11.2** (matches +`plugin.json` per the repo's "version follows repo versioning" rule — bump all +together at the next release cut): + +| Order | Skill folder | Preferred slug | Fallback (only if slug taken) | +|---|---|---|---| +| 1 | `agent-launcher-orchestrator` | `agent-launcher-orchestrator` | `cs-agent-launcher-orchestrator` | +| 2 | `stage-launch` | `stage-launch` | `cs-stage-launch` | +| 3 | `grade-iterate` | `grade-iterate` | `cs-grade-iterate` | +| 4 | `run-without-you` | `run-without-you` | `cs-run-without-you` | +| 5 | `interview` | *likely taken* → `cs-interview` | `cs-agent-interview` | +| 6 | `wrap-up` | *likely taken* → `cs-wrap-up` | `cs-agent-wrap-up` | + +`interview` and `wrap-up` are generic slugs — expect conflicts (upstream +`anthropics/launch-your-agent` itself ships a `wrap-up` skill). Per the repo +rule, the `cs-` prefix applies **only on the ClawHub registry**; never rename the +repo folders. + +## Constraints (from root CLAUDE.md) + +- **Rate limit: 5 new skills/hour** → publish 1–5 in the first batch, 6 after the + window (or let `clawhub-drip.timer` pace all 6). +- **No paid dependencies:** satisfied — all 18 tools are stdlib-only; live CMA + calls are BYOK curl the user runs. +- Version must match the repo release version. + +## Pre-publish checklist + +- [ ] `python3 scripts/derive_counters.py --check` green +- [ ] All 6 SKILL.md frontmatter `version:` fields match `plugin.json` +- [ ] `for f in agent-launcher/skills/*/scripts/*.py; do python3 "$f" --help >/dev/null; done` exits clean +- [ ] Attribution intact: `plugin.json` `attribution` block names + `anthropics/launch-your-agent` (Apache-2.0) +- [ ] Strip the repo-only `source`/`attribution` extension fields at publish time + if the stripping pipeline is active diff --git a/agent-launcher/skills/agent-launcher-orchestrator/README.md b/agent-launcher/skills/agent-launcher-orchestrator/README.md new file mode 100644 index 00000000..11bc98f1 --- /dev/null +++ b/agent-launcher/skills/agent-launcher-orchestrator/README.md @@ -0,0 +1,34 @@ +# agent-launcher-orchestrator + +`context: fork` goal router for the agent-launcher plugin. Reads the per-session +goal (`./my-agent/goal.json`), routes deterministically to a phase sub-skill, and +compiles the goal+phase into an execution shape (single-pass workflow / bounded +grade→iterate loop / recurring cron deployment loop). + +## Usage + +```bash +# manage the goal +python3 scripts/goal_state.py init --goal "Triage my inbox every morning" +python3 scripts/goal_state.py status +python3 scripts/goal_state.py advance + +# route (exit 0 route / 3 ask / 4 refuse) +python3 scripts/goal_router.py --out-dir ./my-agent + +# compile the loop/workflow +python3 scripts/loop_compiler.py --out-dir ./my-agent --max-iterations 5 +``` + +## Tools + +| Tool | Purpose | +|---|---| +| `goal_state.py` | init/set/status/advance `./my-agent/goal.json` | +| `goal_router.py` | goal → phase lane (exit-code route/ask/refuse) | +| `loop_compiler.py` | goal+phase → `plan.v1` (single-pass / grade-iterate / cron-loop) | + +Shared references live at the domain level: [`../../references/`](../../references/) +(see `session-goal-model.md` and `loops-and-workflows.md`). All tools are +stdlib-only and make no network calls. See [`SKILL.md`](SKILL.md) for the full +workflow and forcing questions. diff --git a/agent-launcher/skills/agent-launcher-orchestrator/SKILL.md b/agent-launcher/skills/agent-launcher-orchestrator/SKILL.md index 0c71277b..540e74d7 100644 --- a/agent-launcher/skills/agent-launcher-orchestrator/SKILL.md +++ b/agent-launcher/skills/agent-launcher-orchestrator/SKILL.md @@ -2,7 +2,7 @@ name: agent-launcher-orchestrator description: Use when a user wants to build, launch, grade, or schedule a Claude Managed Agent (CMA) in their own Anthropic account — "build me an agent", "launch this as a managed agent", "run this on a schedule", "grade my agent against a rubric", "set up a nightly worker". Reads the per-session goal (./my-agent/goal.json), routes deterministically to one of five phase sub-skills (interview → stage-launch → grade-iterate → run-without-you → wrap-up) via goal_router.py, and compiles the goal+phase into an execution shape (single-pass workflow / bounded grade→iterate loop / recurring cron deployment loop) via loop_compiler.py. Forks context so heavy intake (build sheets, payloads, eval cases) stays out of the parent thread. All launches are emitted as BYOK curl the user runs with their own key; no tool makes API calls. Inspired by anthropics/launch-your-agent (Apache-2.0). Distinct from engineering/agent-harness (generic domain loop) and engineering/write-a-skill (authors Claude Code skills, not CMAs). context: fork -version: 2.12.0 +version: 2.11.2 author: Alireza Rezvani license: MIT tags: [claude-managed-agents, cma, agent, launch, orchestrator, session-goal, loop, workflow, cron, outcome, byok] diff --git a/agent-launcher/skills/grade-iterate/README.md b/agent-launcher/skills/grade-iterate/README.md new file mode 100644 index 00000000..28c30f1b --- /dev/null +++ b/agent-launcher/skills/grade-iterate/README.md @@ -0,0 +1,24 @@ +# grade-iterate (Phase 3 — the bounded loop) + +CMA's outcome primitive self-grades the agent's work against a required rubric; +this skill builds the outcome, reads each verdict, and scaffolds held-back eval. +Loops are **always bounded** by `max_iterations` (1..20). + +## Usage + +```bash +python3 scripts/outcome_builder.py --sheet ./my-agent/build-sheet.json \ + --max-iterations 5 --out ./my-agent/payloads/outcome.json +python3 scripts/verdict_reader.py --result ./my-agent/last-verdict.json +python3 scripts/eval_scaffold.py --sheet ./my-agent/build-sheet.json --out ./my-agent/eval.json +``` + +## Tools + +| Tool | Purpose | +|---|---| +| `outcome_builder.py` | `user.define_outcome` payload (rubric required, cap clamped 1..20) | +| `verdict_reader.py` | grader result → next move (SHIP / SHARPEN / ESCALATE / RESUME) | +| `eval_scaffold.py` | held-back cases + parallel run plan (≤25 threads) | + +Loop discipline: [`../../references/loops-and-workflows.md`](../../references/loops-and-workflows.md). diff --git a/agent-launcher/skills/grade-iterate/SKILL.md b/agent-launcher/skills/grade-iterate/SKILL.md index a8c79f64..d48be509 100644 --- a/agent-launcher/skills/grade-iterate/SKILL.md +++ b/agent-launcher/skills/grade-iterate/SKILL.md @@ -1,7 +1,7 @@ --- name: grade-iterate description: Phase 3 of building a Claude Managed Agent — the bounded grade→iterate loop. Define a CMA outcome (a required markdown rubric graded by an isolated grader), read each verdict, decide the next move (sharpen / re-run / promote to schedule), and once a version passes, run held-back eval cases in parallel. Use when the user says "grade my agent", "make it pass the rubric", "iterate until it's good", "is it good enough", or when the orchestrator routes phase=grade-iterate. outcome_builder.py builds the user.define_outcome payload (rubric required, max_iterations clamped 1..20 — never unbounded); verdict_reader.py reads the grader result and recommends the next move; eval_scaffold.py generates held-back cases + a parallel run plan (capped at the 25-thread CMA ceiling). Distinct from stage-launch (first launch) and run-without-you (scheduling). -version: 2.12.0 +version: 2.11.2 author: Alireza Rezvani license: MIT tags: [cma, outcome, rubric, grader, grade-iterate, loop, max-iterations, eval, held-back] diff --git a/agent-launcher/skills/interview/README.md b/agent-launcher/skills/interview/README.md new file mode 100644 index 00000000..e49deb00 --- /dev/null +++ b/agent-launcher/skills/interview/README.md @@ -0,0 +1,29 @@ +# interview (Phase 1) + +Interview a founder into a validated Claude Managed Agent **build sheet** — +primitives table + v1/v2 deferrals + eval plan. No API key needed in this phase. + +## Usage + +```bash +python3 scripts/interview_planner.py \ + --job "Triage overnight support email" --trigger schedule \ + --inputs "gmail,memory" --actions "label" \ + --dod "one label per email, grounded reason" --recurrence daily \ + --out ./my-agent/plan.json + +python3 scripts/build_sheet_builder.py --plan ./my-agent/plan.json --out-dir ./my-agent +python3 scripts/primitives_validator.py --sheet ./my-agent/build-sheet.json +``` + +## Tools + +| Tool | Purpose | +|---|---| +| `interview_planner.py` | six intake slots → primitives skeleton + deferrals | +| `build_sheet_builder.py` | assemble/normalize `build-sheet.json` | +| `primitives_validator.py` | validate vs CMA limits (PASS/WARN/FAIL, exit 1 on FAIL) | + +The build-sheet schema and a worked example live in +[`../../assets/`](../../assets/); the intake-slot mapping is documented in +[`../../references/interview-to-config.md`](../../references/interview-to-config.md). diff --git a/agent-launcher/skills/interview/SKILL.md b/agent-launcher/skills/interview/SKILL.md index a0742861..507aacf2 100644 --- a/agent-launcher/skills/interview/SKILL.md +++ b/agent-launcher/skills/interview/SKILL.md @@ -1,7 +1,7 @@ --- name: interview description: Phase 1 of building a Claude Managed Agent — interview the founder about the one job the agent should do, then produce a build sheet (CMA primitives table + v1/v2 deferrals + eval plan) WITHOUT needing their API key yet. Use when the user says "help me scope an agent", "I have an idea for an agent", "what should this agent be", or when the orchestrator routes phase=interview. Drives the six intake slots (job, trigger, inputs, actions, definition-of-done, recurrence) via AskUserQuestion, maps them to primitives with interview_planner.py, assembles build-sheet.json with build_sheet_builder.py, and validates limits with primitives_validator.py. Connectors are mockable in v0 (schema-true custom tools); real MCP servers become v1 deferrals. Distinct from stage-launch (which turns the sheet into payloads). -version: 2.12.0 +version: 2.11.2 author: Alireza Rezvani license: MIT tags: [cma, interview, scoping, build-sheet, primitives, deferrals, eval-plan] diff --git a/agent-launcher/skills/run-without-you/README.md b/agent-launcher/skills/run-without-you/README.md new file mode 100644 index 00000000..f50a80db --- /dev/null +++ b/agent-launcher/skills/run-without-you/README.md @@ -0,0 +1,27 @@ +# run-without-you (Phase 4 — the recurring loop) + +Turn a graded agent into a **recurring POSIX-cron scheduled deployment** (each +firing can nest a self-grading outcome), an event-driven curl trigger, or +confirmed on-demand use. Always test with one manual `run` before trusting the +schedule. + +## Usage + +```bash +python3 scripts/cron_validator.py --cron "0 9 * * *" --timezone Europe/Berlin +python3 scripts/deployment_builder.py --sheet ./my-agent/build-sheet.json \ + --agent-id agent_… --env-id env_… --nest-outcome \ + --out ./my-agent/payloads/deployment.json +python3 scripts/next_directions_writer.py --sheet ./my-agent/build-sheet.json \ + --loop-shape cron-loop --out-dir ./my-agent +``` + +## Tools + +| Tool | Purpose | +|---|---| +| `deployment_builder.py` | `POST /v1/deployments` payload + BYOK create/test-run curl | +| `cron_validator.py` | 5-field POSIX cron + IANA tz + wall-clock DST note (exit 1 on invalid) | +| `next_directions_writer.py` | write/refresh `NEXT-DIRECTIONS.md` from deferrals | + +DST and deployment semantics: [`../../references/cma-primitives.md`](../../references/cma-primitives.md). diff --git a/agent-launcher/skills/run-without-you/SKILL.md b/agent-launcher/skills/run-without-you/SKILL.md index 145c74f0..774261b4 100644 --- a/agent-launcher/skills/run-without-you/SKILL.md +++ b/agent-launcher/skills/run-without-you/SKILL.md @@ -1,7 +1,7 @@ --- name: run-without-you description: Phase 4 of building a Claude Managed Agent — make it run without you. Turn a graded agent into a recurring scheduled deployment (POSIX-cron), an event-driven curl trigger, or confirmed on-demand use, then finalize the versioned roadmap. Use when the user says "run it every morning", "put it on a schedule", "nightly", "weekly", "automate this", "make it recurring", or when the orchestrator routes phase=run-without-you. deployment_builder.py builds the POST /v1/deployments payload (initial_events must include user.message; optionally nests a user.define_outcome so each firing self-grades); cron_validator.py validates the 5-field cron + IANA timezone and prints the wall-clock DST note; next_directions_writer.py writes NEXT-DIRECTIONS.md. No tool makes API calls — the deployment is created via BYOK curl. Distinct from grade-iterate (the in-session loop) and wrap-up (closeout). -version: 2.12.0 +version: 2.11.2 author: Alireza Rezvani license: MIT tags: [cma, deployment, cron, schedule, recurring, run-without-you, next-directions, dst] diff --git a/agent-launcher/skills/stage-launch/README.md b/agent-launcher/skills/stage-launch/README.md new file mode 100644 index 00000000..6d48a3a8 --- /dev/null +++ b/agent-launcher/skills/stage-launch/README.md @@ -0,0 +1,26 @@ +# stage-launch (Phase 2) + +Turn a build sheet into exact CMA API payloads and a **resumable BYOK curl launch +script**. No tool makes API calls; the user runs `launch.sh` with their own +`$ANTHROPIC_API_KEY` — the key is never printed, logged, or written. + +## Usage + +```bash +python3 scripts/payload_generator.py --sheet ./my-agent/build-sheet.json --out-dir ./my-agent +python3 scripts/launch_script_writer.py --out-dir ./my-agent +python3 scripts/payload_validator.py --dir ./my-agent # FAILs on an embedded key + +export ANTHROPIC_API_KEY=... # in your shell, never in chat +./my-agent/launch.sh # env → agent → session → kickoff; re-run resumes +``` + +## Tools + +| Tool | Purpose | +|---|---| +| `payload_generator.py` | build sheet → 4 ordered payloads (env/agent/session/kickoff) | +| `launch_script_writer.py` | resumable BYOK curl launcher (no key handling) | +| `payload_validator.py` | pre-launch check + API-key-leak scan (exit 1 on FAIL) | + +CMA payload semantics: [`../../references/cma-primitives.md`](../../references/cma-primitives.md). diff --git a/agent-launcher/skills/stage-launch/SKILL.md b/agent-launcher/skills/stage-launch/SKILL.md index 8e8501d6..59ac1a82 100644 --- a/agent-launcher/skills/stage-launch/SKILL.md +++ b/agent-launcher/skills/stage-launch/SKILL.md @@ -1,7 +1,7 @@ --- name: stage-launch description: Phase 2 of building a Claude Managed Agent — turn a validated build sheet into exact API payloads and a resumable BYOK curl launch script, then launch (environment → agent → session → kickoff) using the founder's OWN Anthropic key. Use when the user says "launch it", "deploy the agent", "create the agent now", or when the orchestrator routes phase=stage-launch. payload_generator.py emits the four ordered payloads; launch_script_writer.py writes launch.sh that reads $ANTHROPIC_API_KEY at runtime and never embeds it; payload_validator.py runs a pre-launch check including an API-key-leak scan. No tool in this skill makes network calls — the user runs launch.sh themselves. Distinct from interview (planning) and grade-iterate (the outcome loop). -version: 2.12.0 +version: 2.11.2 author: Alireza Rezvani license: MIT tags: [cma, launch, payloads, curl, byok, api-key-safety, environment, agent, session] diff --git a/agent-launcher/skills/wrap-up/README.md b/agent-launcher/skills/wrap-up/README.md new file mode 100644 index 00000000..37ef670e --- /dev/null +++ b/agent-launcher/skills/wrap-up/README.md @@ -0,0 +1,20 @@ +# wrap-up (close-out) + +Recap every CMA primitive the founder owns, regenerate the single-file overview +page, and suggest the next 1–2 upgrades. The last stop before `phase=done`. + +## Usage + +```bash +python3 scripts/primitives_inventory.py --sheet ./my-agent/build-sheet.json --goal ./my-agent/goal.json +python3 scripts/overview_page.py --sheet ./my-agent/build-sheet.json --out-dir ./my-agent --status live +python3 scripts/upgrade_suggester.py --sheet ./my-agent/build-sheet.json --top 2 +``` + +## Tools + +| Tool | Purpose | +|---|---| +| `primitives_inventory.py` | table of everything owned (agent/env/session/memory/outcome/deployment) | +| `overview_page.py` | regenerate self-contained `agent-overview.html` (template in [`../../assets/`](../../assets/)) | +| `upgrade_suggester.py` | rank next moves from deferrals + standing hardening steps | diff --git a/agent-launcher/skills/wrap-up/SKILL.md b/agent-launcher/skills/wrap-up/SKILL.md index 700b922c..0e817828 100644 --- a/agent-launcher/skills/wrap-up/SKILL.md +++ b/agent-launcher/skills/wrap-up/SKILL.md @@ -1,7 +1,7 @@ --- name: wrap-up description: Close out a launched Claude Managed Agent — recap every primitive the founder now owns, regenerate the single-file overview page, and suggest the next 1-2 upgrades. Use when the user says "wrap up", "close this out", "what do I own now", "give me the summary", "recap the agent", or when the orchestrator routes phase=wrap-up. primitives_inventory.py tables everything owned (agent, environment, session, memory, outcome, deployment); overview_page.py regenerates a self-contained ./my-agent/agent-overview.html; upgrade_suggester.py ranks the next moves from recorded deferrals plus standing hardening steps. Companion to run-without-you; the last stop before phase=done. -version: 2.12.0 +version: 2.11.2 author: Alireza Rezvani license: MIT tags: [cma, wrap-up, closeout, inventory, overview, upgrades, next-directions]