{"id":51223106,"url":"https://github.com/LazyIsEfficient/agentic-os","last_synced_at":"2026-07-01T04:00:34.756Z","repository":{"id":362552750,"uuid":"1205548417","full_name":"LazyIsEfficient/agentic-os","owner":"LazyIsEfficient","description":"Agentic Framework for Modern Development","archived":false,"fork":false,"pushed_at":"2026-06-30T04:23:50.000Z","size":3427,"stargazers_count":13,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-30T05:22:36.456Z","etag":null,"topics":["agentic-framework","ai-agents","ai-skills","ai-skills-manager","ai-workflow","claude-code-skills"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LazyIsEfficient.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-09T04:07:22.000Z","updated_at":"2026-06-30T04:23:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"efa2af9c-682f-4497-9610-22cbced93e96","html_url":"https://github.com/LazyIsEfficient/agentic-os","commit_stats":null,"previous_names":["lazyisefficient/agentic-os"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/LazyIsEfficient/agentic-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LazyIsEfficient%2Fagentic-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LazyIsEfficient%2Fagentic-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LazyIsEfficient%2Fagentic-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LazyIsEfficient%2Fagentic-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LazyIsEfficient","download_url":"https://codeload.github.com/LazyIsEfficient/agentic-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LazyIsEfficient%2Fagentic-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34992071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-framework","ai-agents","ai-skills","ai-skills-manager","ai-workflow","claude-code-skills"],"created_at":"2026-06-28T09:00:31.117Z","updated_at":"2026-07-01T04:00:34.741Z","avatar_url":"https://github.com/LazyIsEfficient.png","language":"Python","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"# Engineering Heresy — Agentic Framework\n\nA collection of skills and agents for [Claude Code](https://claude.ai/code) and [Cursor](https://cursor.com) that encode engineering workflows, content pipelines, game development, marketing ops, and more into reusable AI playbooks.\n\nInstall once, use in any project.\n\n\u003e Part of **[Engineering Heresy](https://geggleto.substack.com/)** by Glenn Eggleton — challenging conventional wisdom in AI and software engineering. **[Subscribe on Substack →](https://geggleto.substack.com/)**\n\n---\n\n## Features\n\nAgenticOS (this repository) is a **curated library of AI playbooks** for serious, long-running work in software engineering, game development, marketing, and operations. You install it once into Claude Code or Cursor; from then on, your agent can follow proven workflows instead of improvising every task from scratch.\n\nThe product is not \"more agents for the sake of agents.\" It is a **harness** — structure, guardrails, and reusable expertise wrapped around frontier models so you get **predictable quality at lower token cost**, especially across multi-step sessions where context compression would otherwise cause drift and rework. See [NORTH_STAR.md](NORTH_STAR.md) for the design thesis.\n\n### What you get\n\n| Piece | What it is | How you use it |\n|---|---|---|\n| **Skills** (37) | Step-by-step playbooks for a kind of work — code review, Rust engineering, SEO ops, game balancing, etc. | Ask the agent to use a skill by name, or configure your IDE so skills are checked before every task (see [Usage](#usage)). |\n| **Agents** (16) | Role definitions with a mandate and tool allowlist — engineer, security-reviewer, marketer, rust-engineer, etc. | Spawn explicitly (\"use the code-reviewer agent\") or let the orchestrator dispatch subagents for multi-step work. |\n| **Commands** (3 ship to consumers) | Slash shortcuts — scaffold new skills/agents, record session facts. | Claude Code: `/skill-new`, `/agent-new`, `/state`. Cursor: no slash commands ship; use the `session-state` skill instead of `/state`. |\n| **Hooks** | Small shell scripts that run on IDE events (session start, before shell, before compaction). | Installed and registered automatically; power the [awareness harness](#awareness-harness-experimental). Disable by editing your global hook config. |\n| **Operating rules** | Always-on doctrine for orchestration, memory, grounding, and review tiers. | Clone this repo into a project to use `.cursor/rules/*.mdc` (Cursor) or `.claude/rules/` via `CLAUDE.md` (Claude Code). Not copied by the global installer. |\n\n### Supported platforms\n\n- **[Claude Code](https://claude.ai/code)** — full install: skills, agents, hooks, and three consumer commands. Remote one-liner installs a **pinned, SHA-256–verified release** (`install.sh` / `install.ps1`).\n- **[Cursor](https://cursor.com)** — parallel install path: skills and agents from the shared `.claude/` tree, Cursor-native hooks, no slash commands. Remote one-liner: `install-cursor.sh` / `install-cursor.ps1`.\n\nBoth paths share the same skill and agent markdown; only install location and hook wiring differ.\n\n### Workflow domains\n\nSkills and agents are grouped by the work they cover. Invoke the one that matches your task; shaper skills (`prompt-shaper`, `marketing-shaper`, `game-design-shaper`) turn vague requests into scoped briefs first.\n\n**Software engineering**\n\n- Full-stack implementation (`engineer`, `devops-engineer`)\n- Language specialists: Rust (`rust-engineer`), TypeScript testing (frontend/backend), data pipelines and analytics\n- Smart contracts and EVM development (`web3-engineer`, `web3-smart-contract-engineering`)\n- CI/CD and deployment pipelines\n- Planning and task breakdown for parallel subagent dispatch\n- Release coordination across a monorepo\n- Codebase cost estimation (LOC/complexity → build cost)\n\n**Quality, security, and review**\n\n- Multi-axis code review (`code-reviewer`, `code-review-and-quality`)\n- Cross-stack security audit (`security-reviewer`, `security-engineering`)\n- PII scan and redaction (`security`)\n- Adversarial review of formal claims — math, stats, benchmarks (`adversarial-claims-reviewer`)\n- API/persistence cataloging into `DATA_MODEL.md` (`data-model-documenter`, `data-model-documentation`) with adversarial verification (`data-model-verifier`)\n\n**Game development**\n\n- Godot 4 + C# (`godot-engineer`)\n- Phaser 3 + TypeScript (`phaser-engineer`)\n- Systems design, economy balancing, IAP catalog design (`game-systems-designer`, `game-balancer`, `iap-manager`)\n- End-to-end game design pipeline (`game-design-shaper`)\n\n**Marketing, growth, and revenue**\n\n- Marketing intake and full-spectrum execution (`marketing-shaper`, `marketer`)\n- Content scoring with an expert panel (`content-ops`)\n- Content production pipeline — quotes, clips, repurposing (`content-pipeline`)\n- SEO, CRO, growth experiments, cold outbound, revenue attribution (`seo-ops`, `conversion-ops`, `growth-engine`, `outbound-engine`, `revenue-intelligence`)\n- Karpathy-style autoresearch on conversion content (`autoresearch`)\n\n**Browser and tooling**\n\n- Real-browser testing via Chrome DevTools MCP (`browser-testing-with-devtools`)\n\n**Library maintenance** (for contributors and fork maintainers)\n\n- Scaffold conforming skills and agents (`/skill-new`, `/agent-new`)\n- Structural audit of the library (`library-reviewer`, `library-investigator`, `skill-library-review`)\n- Sharded full-library audit workflow (`/audit-library` — repo-local)\n- Stochastic finding triage and ratchet promotion (`findings-ledger`, `/triage-findings`)\n\n### Harness capabilities\n\nThese are features of the **framework itself**, not individual skills:\n\n**Awareness harness (experimental)** — Fights the dominant failure mode of long agent sessions: losing track of settled decisions and existing infrastructure. Externalizes live session state in `SESSION-STATE.md`, re-injects it via hooks at session start and each turn, checkpoints before compaction, and nudges \"survey before you provision.\" Includes deterministic metrics to compare hook-ON vs hook-OFF sessions. [Activation guide →](docs/awareness-harness-activation.md)\n\n**Orchestrator + ship gates** — Operating doctrine treats the main agent as an orchestrator that dispatches specialists (`Task` in Cursor, `Agent` in Claude Code) instead of doing multi-step work inline. After implementation, a fixed review DAG runs: code review, security review, optional library review, and conditional data-model documentation/verification. PR checkboxes and CI (`check-pr-ship-gates`) enforce the gate. Canonical graph: [gate-dag.md](.claude/references/gate-dag.md).\n\n**Review tiers** — Findings are sorted by reproducibility: Tier 0 deterministic checks hard-block; Tier 1 LLM findings need an evidence artifact; Tier 2 is advisory and logged to the findings ledger for recurrence-based promotion into deterministic checks.\n\n**Persistent memory** — Two layers: within-session facts in `SESSION-STATE.md` (hook-driven, gitignored); cross-session personal/project memory in `.claude/memory/` (gitignored, in-repo when you clone). Never hand-edit session state — use `/state` or the `session-state` writer script.\n\n**Deterministic validation** — `scripts/validate.sh` is an LLM-free gate on every PR: frontmatter, naming, dangling links, ship manifest, hook safety, tombstones for removed skills, and more. Install scripts refuse to copy a library that fails validation. Enable `.githooks` pre-commit for local enforcement.\n\n**Pinned, verified releases** — Remote installs download a tagged tarball and abort on SHA-256 mismatch. No \"track main\" remote path — unreleased work installs from a local clone. Maintainer runbook: [RELEASING.md](RELEASING.md).\n\n**Telemetry (opt-in)** — Local-first usage telemetry skill; privacy-respecting, not shipped as silent analytics.\n\n**Security model for hooks** — Shipped hook scripts are auditable shell, no runtime network, human-reviewed before merge, and scanned by validator Invariant 8. Injected session files are treated as untrusted data. Details: [SECURITY.md](SECURITY.md).\n\n### How to get started\n\n1. **Install** for your IDE — [Cursor](#cursor) or [Claude Code](#claude-code) section below.\n2. **Configure skill discipline** — add the Skills block from [Usage](#usage) to `~/.claude/CLAUDE.md` or Cursor User Rules so agents reach for skills by default.\n3. **Initialize session state** (optional but recommended for long sessions) — `/state init` (Claude Code) or `session-state.sh init` (Cursor).\n4. **Pick a workflow** — e.g. \"Use `prompt-shaper` to scope this feature, then dispatch `engineer` to implement.\"\n5. **Contributing?** — scaffold with `/skill-new` or `/agent-new`, run `library-reviewer` on your diff, ensure `bash scripts/validate.sh` passes. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n### Maintainer-only (not installed globally)\n\nCloned-repo tooling for library authors: `/audit-library`, `/review-gate`, `/eval-harness`, `/triage-findings`, `workflows/`, `eval/` comparative harness, `scripts/release.sh`, and full CI workflow in `.github/workflows/`. Consumers get the skills, agents, hooks, and three commands only.\n\n---\n\n## Install\n\nTwo consumer paths — **Cursor** and **Claude Code** — share the same skill/agent markdown from this repo but install to different global config dirs. Each section below is self-contained; you do not need to read the other platform's section.\n\nBoth remote one-liners install a **pinned release** and verify its SHA-256 before extracting anything — see [Verifying the download](#verifying-the-download).\n\n- **Current release:** `v2.5.0`\n- **Asset:** `agentic-os-v2.5.0.tar.gz`\n- **SHA-256:** `a012d5bf9066b9cb0992deaf6cf24500465157c1d264aa154cc792eccce7146c`\n\n### Cursor\n\nInstall skills, agents, and **active** hook registration into `~/.cursor/`. Shared content is sourced from the repo's `.claude/` tree; Cursor-specific operating rules live in this repo under `.cursor/rules/*.mdc` (clone the repo into a project to use them — they are not copied by the global installer).\n\n**macOS / Linux — one-liner (no clone required):**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/LazyIsEfficient/agentic-os/v2.5.0/install-cursor.sh | bash\n```\n\n**Or from a local clone:**\n\n```bash\ngit clone https://github.com/LazyIsEfficient/agentic-os.git\ncd agentic-os\n./install-cursor.sh\n```\n\nFiles are copied to `~/.cursor/skills/`, `~/.cursor/agents/`, and `~/.cursor/hooks/`. Existing files are not overwritten by default. Add `--force` to update everything.\n\n**Maintainer dev sync:** for active work on this repo, use the checkout paths (`.claude/skills/`, `.claude/agents/`, `.cursor/rules/`) directly — or symlink `~/.cursor/skills` / `~/.cursor/agents` to the repo's `.claude/` trees if you want global Cursor to track the clone live. Skill script paths: [findings-ledger/references/install-paths.md](.claude/skills/findings-ledger/references/install-paths.md) (repo uses `.claude/skills/`; `~/.cursor/skills/` is post-install only).\n\n**Persistent memory:** `.claude/memory/` is gitignored (machine-local). `validate.sh` scans it when present on your machine — fix dangling wikilinks locally; CI does not see memory files.\n\n**Custom install path:**\n\n```bash\nCURSOR_DIR=/path/to/.cursor ./install-cursor.sh\n```\n\n**Windows:** use `install-cursor.ps1` for parity (or run `install-cursor.sh` from Git Bash/WSL).\n\n**Session-state writer** (full resolution chain — see [install-paths.md](.claude/skills/findings-ledger/references/install-paths.md)):\n\n```bash\nPROJ=\"${CURSOR_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}\"\nSS=\"$PROJ/.claude/skills/session-state/scripts/session-state.sh\"\n[ -f \"$SS\" ] || SS=\"$HOME/.cursor/skills/session-state/scripts/session-state.sh\"\n[ -f \"$SS\" ] || SS=\"$HOME/.claude/skills/session-state/scripts/session-state.sh\"\nbash \"$SS\" init\n```\n\nAfter `install-cursor.sh` only, the global `$HOME/.cursor/skills/…` path alone is usually enough.\n\nThere is no `/state` slash command on Cursor. Invoke the `session-state` skill (or ask the agent to record a session fact) and it runs the writer via Bash — see [.claude/skills/session-state/SKILL.md](.claude/skills/session-state/SKILL.md).\n\nRestart Cursor after install so new skills and agents load.\n\n### Claude Code\n\n#### macOS / Linux\n\n**One-liner (no clone required):**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/LazyIsEfficient/agentic-os/v2.5.0/install.sh | bash\n```\n\n**Or from a local clone:**\n\n```bash\ngit clone https://github.com/LazyIsEfficient/agentic-os.git\ncd agentic-os\n./install.sh\n```\n\nFiles are copied to `~/.claude/skills/`, `~/.claude/agents/`, and `~/.claude/commands/`. Existing files are not overwritten by default. Add `--force` to update everything.\n\n#### Windows (PowerShell)\n\n**One-liner (no clone required):**\n\n```powershell\nirm https://raw.githubusercontent.com/LazyIsEfficient/agentic-os/v2.5.0/install.ps1 | iex\n```\n\n**Or from a local clone:**\n\n```powershell\ngit clone https://github.com/LazyIsEfficient/agentic-os.git\ncd agentic-os\n.\\install.ps1\n```\n\nFiles are copied to `%USERPROFILE%\\.claude\\skills\\`, `%USERPROFILE%\\.claude\\agents\\`, and `%USERPROFILE%\\.claude\\commands\\`. Add `-Force` to overwrite existing files. (The remote install uses `tar`, which ships with Windows 10 1803+.)\n\n#### Verifying the download\n\nThe remote install path downloads the pinned release asset and aborts if its\nSHA-256 does not match the digest embedded in the installer. To verify\nout-of-band before trusting the one-liner, download the asset and check it\nyourself:\n\n```bash\ncurl -fsSLO https://github.com/LazyIsEfficient/agentic-os/releases/download/v2.5.0/agentic-os-v2.5.0.tar.gz\n# macOS / BSD:\necho \"a012d5bf9066b9cb0992deaf6cf24500465157c1d264aa154cc792eccce7146c  agentic-os-v2.5.0.tar.gz\" | shasum -a 256 -c\n# Linux (coreutils):\necho \"a012d5bf9066b9cb0992deaf6cf24500465157c1d264aa154cc792eccce7146c  agentic-os-v2.5.0.tar.gz\" | sha256sum -c\n```\n\nThere is intentionally no \"track `main`\" remote install path — to install\nunreleased changes, clone the repo and run `./install.sh` from the clone.\nMaintainers: see [RELEASING.md](RELEASING.md) for how the pin is produced.\n\n#### Custom install path\n\nHook registration paths are rewritten to match `CLAUDE_DIR` / `-Dest` at install (requires `jq` on bash).\n\n```bash\nCLAUDE_DIR=/path/to/.claude ./install.sh\n```\n\n```powershell\n.\\install.ps1 -Dest \"C:\\path\\to\\.claude\"\n```\n\n---\n\n## What gets installed\n\n### Cursor (`install-cursor.sh`)\n\n| Directory | Contents |\n|---|---|\n| `~/.cursor/skills/` | Skill playbooks — Cursor discovers these globally; invoke by name in Agent chat |\n| `~/.cursor/agents/` | Subagent definitions — spawn by name when Cursor routes or when you request one |\n| `~/.cursor/hooks/` | Cursor-native hook scripts — registered globally in `~/.cursor/hooks.json` on install |\n\n\u003e **Ship vs. in-repo-only.** The Cursor installer copies the full `skills/` and `agents/` trees from `.claude/` plus production hook scripts from `.cursor/hooks/` (spike `*-probe.sh` excluded). Slash commands do **not** ship on Cursor (no `/state`; use the `session-state` skill + writer). Maintainer-only commands and `workflows/` are repo-local. Operating doctrine for Cursor lives in this repo's `.cursor/rules/*.mdc` — clone into a project to use; it is not copied to `~/.cursor/` by `install-cursor.sh`.\n\n### Claude Code (`install.sh`)\n\n| Directory | Contents |\n|---|---|\n| `~/.claude/skills/` | Skill playbooks — invoked with the `Skill` tool or `/skill-name` |\n| `~/.claude/agents/` | Subagent definitions — spawned with the `Agent` tool |\n| `~/.claude/commands/` | Slash commands — `/skill-new` and `/agent-new` scaffold a new conforming skill or agent; `/state` records a durable session fact via the awareness-harness writer |\n| `~/.claude/hooks/` | Hook scripts — registered globally in `~/.claude/settings.json` on install (awareness harness + `block-bad-bash`) — see [Awareness harness](#awareness-harness-experimental) |\n\n\u003e **Ship vs. in-repo-only.** The installer copies the full `skills/`, `agents/`, and `hooks/` directories; only **commands** are file-allowlisted (`skill-new`, `agent-new`, `state`). Maintainer-only tooling that lives in this repo — the `audit-library` / `review-gate` / `triage-findings` / `eval-harness` commands and the `workflows/` (the sharded library audit) — is **not** installed, to avoid polluting your command namespace.\n\n---\n\n## Usage\n\n### Invoking a skill\n\nIn any Claude Code conversation, reference a skill by name:\n\n```\nUse the code-review-and-quality skill to review this diff before merge.\n```\n\nOr use a slash command if configured:\n\n```\n/rust-engineer\n```\n\nAgents are spawned automatically when Claude Code routes a task (e.g. `engineer`, `code-reviewer`), or you can request one explicitly:\n\n```\nUse the security-reviewer agent to audit this PR.\n```\n\n### Skills vs Agents\n\n**Skills** are instruction playbooks — they tell Claude *how* to do a specific type of work (code review, Rust engineering, smart-contract development). They are stateless and composable.\n\n**Agents** are role definitions — they give Claude a persona, a tool allowlist, and a mandate (e.g. a full-stack engineer, a security auditor). Agents can invoke skills.\n\n### Awareness harness (experimental)\n\nAn in-development capability ([NORTH_STAR.md](NORTH_STAR.md) / [V2_ROADMAP.md](V2_ROADMAP.md)) that fights the dominant failure mode of long agent sessions: **awareness drift** — finite context compresses, so settled facts get re-derived and existing infrastructure gets rebuilt. It externalizes state and re-surfaces it deterministically via IDE hooks:\n\n- **`SESSION-STATE.md`** — a live, gitignored constraints/decisions/infra/threads doc. Hooks inject it at session start, inject a compact digest each turn, and checkpoint before compaction. Maintained only through the deterministic writer (Claude: `/state`; Cursor: `session-state` skill + Bash), never hand-edited.\n- **survey-before-act** — on a service-provisioning command, reminds you to check whether it already exists first (warn-first; logs for measurement, does not block).\n- **block-bad-bash** — nudges away from `cd \u0026\u0026 git` and long `\u0026\u0026` shell chains (ergonomics, not security; can block routine agent shell — remove the hook entry if annoying).\n- **`eval/metrics/`** — deterministic instruments (`session-metrics.mjs`, `compare.mjs`) that measure tokens-per-outcome and awareness signals, ON (hooks) vs OFF (baseline).\n\n**Ship posture:** hooks are **on by default** after install — `install.sh` / `install-cursor.sh` merge hook registration into `~/.claude/settings.json` and `~/.cursor/hooks.json`. Re-install **replaces the whole `hooks` block**. Remove the `hooks` key to disable.\n\n**→ [Activation guide](docs/awareness-harness-activation.md)** — what's registered, how to turn off, verify steps.\n\n**Cursor hook verification (automated — CI on every PR):**\n\n| Hook | Status | Gate script |\n|---|---|---|\n| `sessionStart` inject | **CONTRACT-VERIFIED** | `scripts/session-state-test-cursor.sh` |\n| `beforeSubmitPrompt` digest | **CONTRACT-VERIFIED** | `scripts/session-state-test-cursor.sh` |\n| `beforeShellExecution` block-bad-bash | **CONTRACT-VERIFIED** | `scripts/block-bad-bash-test-cursor.sh` |\n| `beforeShellExecution` survey | **CONTRACT-VERIFIED** | `scripts/survey-guard-test-cursor.sh` |\n| `preCompact` checkpoint | **CONTRACT-VERIFIED** (side-effect log) | `eval/spikes/cursor-hook-capability/run-automated.sh` |\n\nOne-liner: `bash eval/spikes/cursor-hook-capability/run-automated.sh`. No manual Cursor UI repro is required — see [automated verification protocol](eval/spikes/cursor-hook-capability/LIVE-FIRE-PROTOCOL.md).\n\nSee also [cursor hook capability spike](eval/spikes/cursor-hook-capability.md). Global `install-cursor.sh` copies the same production `.cursor/hooks/` scripts (excluding spike probes) to `~/.cursor/hooks/`.\n\nTreat any hook-injected file as untrusted data — see [SECURITY.md](SECURITY.md) (dual-platform hook surface; Cursor install details in [#153](https://github.com/LazyIsEfficient/agentic-os/issues/153)).\n\n### Configure ~/.claude/CLAUDE.md\n\nSkills are available to Claude, but Claude won't automatically reach for them unless instructed to. Add the following to `~/.claude/CLAUDE.md` to make Claude check for a relevant skill before responding to any task:\n\n```markdown\n## Skills\n\nYou have a library of skills installed at `~/.claude/skills/`. Before responding to any task,\ncheck whether a skill applies and invoke it with the `Skill` tool if so — even if the task\nseems simple.\n\nIf there is even a 1% chance a skill might apply, invoke it first.\n```\n\nThis is the single most impactful configuration step — without it, Claude treats skills as\nopt-in rather than default.\n\n### Configure Cursor rules + skill discipline\n\nOperating doctrine for this repo lives in `.cursor/rules/*.mdc` (YAML frontmatter with `alwaysApply: true`). Cursor requires the **`.mdc`** extension — plain `.md` files in `.cursor/rules/` are not loaded. Clone the repo into a project to use them, or copy the rules into your project's `.cursor/rules/`.\n\n`AGENTS.md` at the repo root is auto-loaded by Cursor (project-root plain markdown). Full doctrine: `.cursor/rules/*.mdc` (`alwaysApply: true`). `CURSOR.md` is the maintainer index (parallel to `CLAUDE.md`).\n\n**Orchestrator gap:** rules steer dispatch but do not enforce it on their own (Tier 2). The Tier 0/1 dispatch-gate hooks ([docs/dispatch-enforcement.md](docs/dispatch-enforcement.md)) enforce it mechanically but ship **disabled** by default. See [cursor-orchestrator-gap.md](docs/cursor-orchestrator-gap.md) for session-state constraints, User Rules, and transcript measurement.\n\nFor **default skill invocation + orchestrator dispatch** across projects, add **both** blocks below to **Cursor Settings → Rules → User Rules** (`subagent-dispatch.mdc` alone is often insufficient — models may load skills inline instead of dispatching).\n\n**Skills + orchestration** (add to **Cursor Settings → Rules → User Rules**):\n\n```markdown\n## Skills\n\nYou have a library of skills installed at `~/.cursor/skills/`. Before responding to any task,\ncheck whether a skill applies — even if the task seems simple.\n\nIf there is even a 1% chance a skill might apply, identify it first. Do NOT run multi-step\nskill workflows on the main thread: brief a subagent (`Task`) with the skill procedure instead.\n\n## Orchestration (Cursor)\n\nYou are an orchestrator. Use Agent mode and the `Task` tool for non-trivial work.\n- Implementation → `Task(engineer)` or domain specialist — not main-thread Write/StrReplace.\n- Research beyond 2–3 reads/greps → `Task(explore)` or `generalPurpose`.\n- Before saying done on code changes → `Task(code-reviewer)` + `Task(security-reviewer)` in parallel (readonly).\n- Fan out independent `Task` calls in one message; sequential dispatch when parallelizable is a bug.\n```\n\nFor long sessions, run `session-state.sh init-orchestrator` (see [cursor-orchestrator-gap.md](docs/cursor-orchestrator-gap.md)) so constraints re-inject every turn.\n\nLegacy **skills-only** block (use the combined block above instead):\n\n```markdown\n## Skills\n\nYou have a library of skills installed at `~/.cursor/skills/`. Before responding to any task,\ncheck whether a skill applies and read its SKILL.md if so — even if the task seems simple.\n\nIf there is even a 1% chance a skill might apply, load the skill first.\n```\n\nRepo maintainers: `CURSOR.md` at the repo root `@`-imports enumerated `.cursor/rules/*.mdc` files (parallel to `CLAUDE.md`).\n\n---\n\n## Skills\n\n| Skill | Description |\n|---|---|\n| `adversarial-claims-reviewer` | Adversarially review formal/technical claims — math, stats, benchmarks, whitepapers |\n| `autoresearch` | Run Karpathy-style autoresearch optimization on any conversion content |\n| `browser-testing-with-devtools` | Test in real browsers via Chrome DevTools MCP |\n| `code-review-and-quality` | Multi-axis code review across correctness, design, security, performance |\n| `codebase-cost-estimator` | Estimate build/dev cost of a codebase by measured LOC and complexity |\n| `data-model-documentation` | Catalog APIs, persistence, and message shapes into `DATA_MODEL.md` |\n| `data-model-verification` | Adversarially verify DATA_MODEL.md property rows against Source files |\n| `content-ops` | Score content with an auto-assembled expert panel until it hits 90+ |\n| `content-pipeline` | Non-interactive content production — quote mining, clip discovery, repurposing, gating |\n| `conversion-ops` | AI-powered CRO — landing-page audits, survey segmentation, lead magnets |\n| `deployment-pipelines` | Author or review CI/CD pipelines and deployment workflows |\n| `findings-ledger` | Record and triage stochastic (Tier 2) review findings for recurrence |\n| `game-balancer` | Tune game economy curves, progression, drop tables, and balance |\n| `game-systems-designer` | Design game systems from a locked concept |\n| `godot-engineer` | Build games in Godot 4 with C# |\n| `growth-engine` | Autonomous growth experimentation with statistical analysis |\n| `iap-manager` | Design and operate the in-app purchase catalog |\n| `library-investigator` | Forensic, evidence-only library audit against RULESET.md |\n| `marketing-shaper` | Structure a vague marketing request into a scoped brief |\n| `outbound-engine` | Design and optimize cold outbound email campaigns on Instantly |\n| `phaser-engineer` | Build games in Phaser 3 with TypeScript |\n| `planning-and-task-breakdown` | Break work into ordered, parallel-dispatchable tasks |\n| `prompt-shaper` | Structure a vague engineering request into a task brief |\n| `release-manager` | Coordinate release preparation across a monorepo |\n| `revenue-intelligence` | AI-powered revenue intelligence and content-to-revenue attribution |\n| `rust-engineer` | Write, review, or architect Rust code |\n| `security` | Scan and redact PII and sensitive data |\n| `security-engineering` | Cross-stack security review covering all attack surfaces |\n| `seo-ops` | AI-powered SEO operations and keyword intelligence |\n| `session-state` | Maintain SESSION-STATE.md — durable within-session memory that survives compaction |\n| `skill-library-review` | Audit a library of skills, agents, commands, and workflows |\n| `telemetry` | Opt-in, local-first, privacy-respecting usage telemetry |\n| `typescript-analytics` | Implement analytics with PostHog in TypeScript |\n| `typescript-data-engineering` | Build data pipelines, ETL jobs, and event processors |\n| `typescript-testing-backend` | Write backend tests with Jest and Supertest |\n| `typescript-testing-frontend` | Write frontend tests with Jest and React Testing Library |\n| `web3-smart-contract-engineering` | Write and review Solidity smart contracts |\n\n---\n\n## Agents\n\n| Agent | Description |\n|---|---|\n| `adversarial-claims-reviewer` | Read-only, cold-context adversarial review of formal/technical claims |\n| `code-reviewer` | Read-only multi-axis code review |\n| `data-model-documenter` | Catalog APIs, models, and message shapes into `DATA_MODEL.md` at project root |\n| `data-model-verifier` | Read-only verification of DATA_MODEL.md property rows against Source files |\n| `devops-engineer` | Platform and DevOps engineering for Kubernetes, Helm, Pulumi IaC, and CI/CD mechanics |\n| `engineer` | Full-stack implementation across architecture and shipping |\n| `game-design-shaper` | Game design pipeline — intake → design → balance → catalog; marketing → marketer agent |\n| `godot-engineer` | Godot 4 + C# game development |\n| `library-investigator` | Read-only forensic library audit against RULESET.md — evidence-only counts, no verdict |\n| `library-reviewer` | Read-only audit of a skill and agent library |\n| `marketer` | Full-spectrum marketing, content, and sales execution |\n| `phaser-engineer` | Phaser 3 + TypeScript web game development |\n| `rust-engineer` | Principal-level Rust engineering — async services, APIs, workspaces |\n| `security-reviewer` | Read-only cross-stack security audit |\n| `technical-pm` | Product strategy, technical strategy, and engineering leadership |\n| `web3-engineer` | Solidity smart contract development on EVM chains |\n\n---\n\n## Commands\n\nSlash commands in `.claude/commands/`. Only `agent-new`, `skill-new`, and `state` (the awareness-harness writer) ship to consumers; the rest are repo-local maintainer tools.\n\n| Command | Description |\n|---|---|\n| `agent-new` | Scaffold a new conforming agent definition |\n| `audit-library` | Launch the sharded, adversarially-verified skill-library audit |\n| `eval-harness` | Run the comparative eval harness over fixtures with a blind pairwise judge panel |\n| `review-gate` | Run the Pattern-3 gate DAG (waves per `.claude/references/gate-dag.md`); `scripts/gate-plan.sh` lists required PR checkboxes |\n| `skill-new` | Scaffold a new conforming skill |\n| `state` | Record a durable session fact to SESSION-STATE.md via the deterministic writer |\n| `triage-findings` | Tally the findings ledger and propose ratchet targets (human disposes) |\n\n---\n\n## Repository layout\n\n```\n.claude/\n├── skills/\u003cskill-name\u003e/\n│   ├── SKILL.md          # frontmatter + rules (target \u003c100 lines)\n│   ├── references/       # deep-dive docs loaded on demand\n│   ├── assets/           # fill-in templates (ADRs, RFCs, briefs)\n│   └── scripts/          # runnable helpers\n├── agents/\u003cagent-name\u003e.md\n├── commands/\u003ccommand\u003e.md # slash commands (author-facing + maintainer-only)\n├── hooks/                # PreToolUse hooks (e.g. block-bad-bash.sh)\n├── rules/                # operating doctrine, @-imported by CLAUDE.md\n└── workflows/            # multi-agent orchestration scripts\n```\n\n\u003e Installers copy full `skills/`, `agents/`, and `hooks/` directories (commands are file-allowlisted on Claude Code only). `CLAUDE.md`, `CURSOR.md`, and `rules/` are repo-local and never installed.\n\n---\n\n## Contributing\n\nPull requests welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for conventions and review gates. The short version: scaffold with `/skill-new` or `/agent-new`, run the `library-reviewer` agent on your diff, and make sure `bash scripts/validate.sh` passes.\n\n---\n\n## Validating the library\n\nA deterministic, LLM-free validator checks structural invariants — frontmatter completeness, kebab-case names matching their file/dir, no dangling links or `@`-imports (`CLAUDE.md` and `CURSOR.md`), `MEMORY.md` length, review-tier wiring (and findings-ledger shape, if present), and that the install scripts ship exactly the expected directories and command allowlist.\n\nEnable the pre-commit hook once per clone so the validator runs before every commit:\n\n```sh\ngit config core.hooksPath .githooks\n```\n\nRun it manually any time:\n\n```sh\nbash scripts/validate.sh\n```\n\nCI enforces the same check on every pull request and push to `main`, and `install.sh` runs it before copying anything — a library that fails validation will not install.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLazyIsEfficient%2Fagentic-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLazyIsEfficient%2Fagentic-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLazyIsEfficient%2Fagentic-os/lists"}