convez.ai
SkillAutomaçãoAvançado
ephes

Agent Stuff - Habilidades Reutilizáveis para Agentes de Código

ephes/agent-stuff

Skills modulares para orquestração e coordenação de agentes de código

Ver no GitHub
InicialPluginScore · de 0 a 100

Coleção pública de skills, extensões e configurações para agentes de código como Codex e Claude. Inclui fluxos de trabalho para commit, revisão cruzada entre agentes, coordenação multi-agente e integração com ledger de trabalho. Distribuído via symlinks chezmoi para manutenção centralizada.

Instalação

$npx convez-ai ephes/agent-stuff

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 dia
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Coordenar múltiplos agentes de IA em fluxos de trabalho complexos
  • Implementar ciclos de revisão cruzada entre diferentes famílias de modelos
  • Gerenciar fila de trabalho e distribuição de tarefas entre workers
  • Automatizar validação, commit e sincronização de documentação

Veredito

Projeto maduro e bem estruturado para quem precisa orquestrar múltiplos agentes de IA em produção. A arquitetura é sofisticada (ledger, escalação, roles definidos) e assume complexidade real, não é ferramenta iniciante. Código Python testado em cenários multi-agente reais.

README

A tradução para o português deste README ainda está na fila.

agent-stuff

Public home for reusable coding agent skills, distributed to each agent via chezmoi symlinks.

Skill inventory

AgentSkillPurpose
Codexcommit-workflowInspect, validate, and commit changes with docs sync
Codex, Claudecross-agent-review-cycleCanonical value-driven different-family review loop; owns the continuation, stopping, containment, effort-escalation, hard-case escalation (Claude Fable 5.2 on the second Claude account, only for disputes, non-converging loops and hard problems), and commit-gate rules. One shared copy under codex/skills/, symlinked for both agents
Codex, Claude, Piwork-ledgerHow coordinators read and update the work app through its work CLI/API (on the Studio via the chezmoi-managed work command, which loads the token without echoing it) (stage ladder, verify-before-write, progress notes, agent attribution and the lost-update guard, C-class owner requests and responses (no routine acceptance asks), usage reports; the owner steers in the coordinator chat (recorded in the ledger); /plan/ and work next are an optional overview, coordination/codex/queue.txt is the operational Codex dispatch list; check the owner's rejections with work rejected before proposing work). Agent-neutral like cross-agent-review-cycle: one copy under codex/skills/, symlinked for every agent
Codex, Claude, Pimulti-agent-coordinationHow a coordinator runs many workers: roles (coordinator; Codex workers commit codex-q/<job> on a local branch in their clone and push nothing; Claude clerks fetch it, review, merge locally, push only main/develop and deploy; scouts), campaign setup (a brief may override worker and reviewer effort, the escalation model and account, the park rule and merge-request-only delivery), handoff doorbell and herdr pane safety, worker brief checklist (incl. bundling), quota pacing (Codex feeder, autoround with merge-backlog brake from merged.txt/dropped.txt, automatic merge clerks), A/B/C decision classes (act and inform / independent check / rare owner decision; vital services, digest, answer bursts), infrastructure and cleanup safety; the owner's chat instructions and delegated mandate are authoritative, /plan/ is optional; no re-proposing ideas the owner rejected (work rejected). Agent-neutral; one copy under codex/skills/, symlinked for every agent
Claudecoordinator-startRestart procedure for the owner's coordinator session in ~/projects/matters: loads multi-agent-coordination and work-ledger, reconstructs the owner's mandate from the ledger, runs the periodic check (usage of all three pools, owner responses, herdr, Codex feeder/autoround/queue, automatic merge clerks running and merged.txt progressing, manual clerks only for what those miss), reports in German and sets up exactly one recurring 30-minute check. One copy under codex/skills/, symlinked into ~/.claude/skills
Codexgoal-handoffGenerate a compact goal condition for another agent session
Codeximplement-handoffGenerate an implementation prompt for a second agent
Codexclaude-review-loopRun the supervised, fail-closed Claude review gate with a configurable model (Opus 5.5 at medium effort by default), working in a sandboxed throwaway copy of the repository; a Suggestion-only round exits 0 as SUGGESTIONS_ONLY; CLAUDE_CONFIG_DIR selects the Claude account that reviews; default reviewer for Codex and Pi implementers
Codexreview-handoffGenerate a code review prompt for a second agent
Claudegoal-handoffGenerate a compact goal condition for another agent session
Claudehandoff-implGenerate an implementation prompt for a second agent
Claudehandoff-reviewGenerate a code review prompt for a second agent
Claudepi-review-loopFail-closed Pi gate using only openai-codex/gpt-6.1-sol at medium thinking (high on request), working in an unsandboxed throwaway copy of the repository; shares the bundle and slice ledger with claude-review-loop
Claudecodex-review-loopDefault reviewer for Claude implementers: fail-closed Codex gate using only gpt-6.1-sol at high reasoning (medium on request, --effort medium); proves the model from Codex's session record (--cyber-access-program daybreak_blue runs gpt-daybreak-blue-latest instead, only for explicitly requested security reviews), confines the reviewer to a sandboxed throwaway copy of the repository, and shares the bundle, slot pool and slice ledger with claude-review-loop
Claudeclaude-review-loop (shared dependency)Supervised gate provided by the sibling Codex skill
Claudecmsg (command)Commit with a clean message, no self-references
Picommit-readyAssess commit readiness without creating a commit
Picommit-workflowInspect, validate, and commit changes with docs sync
Pireview-handoffGenerate a code review prompt for a second agent

Tools

ToolPurpose
tools/workspace-gcLive inventory of agent checkouts under ~/workspaces (classes A removable / B after push / C needs owner / D keep), guarded removal of class A and of leftover empty workspace directories (dry run by default), a report of workspace directories that hold no checkout, and the daily Studio job that removes both and writes the report; Codex job clones go once their job is in the coordination merged.txt/dropped.txt (legacy pushed clones: branch gone and every patch on the integration branch). The work-ledger closeout step uses its single-path remove
tools/codex-quota-guardExits 3 while the Codex subscription limit is used up (Codex would spend paid credits instead of refusing); read from Codex's session records. codex-review-loop and pi-review-loop run it before every review; Codex worker launchers call it first
tools/claude-usage-readReads a Claude account's weekly usage (percent, reset time) through claude -p /usage instead of the interactive /usage dialog, which blocked a worker pane; --report sends it to work usage report
tools/pane-watchdogRead-only scan of herdr panes on given machines for open /usage, trust and permission dialogs, finished turns that ask the owner a question, and typed input; ignores dim ghost-text suggestions and never sends keys
tools/guard-projectsOpt-in Claude Code PreToolUse hook that keeps ~/projects read-only for agents and blocks pushes outside github.com/ephes/, plus check-push-remote for pre-push checks

CI

GitHub Actions (.github/workflows/ci.yml) runs on pushes to main and on pull requests, with no secrets:

  • the hermetic unittest suites of claude-review-loop, codex-review-loop, pi-review-loop, tools/workspace-gc, tools/guard-projects, tools/codex-quota-guard, tools/claude-usage-read and tools/pane-watchdog, on a macOS runner because the harnesses target the Studio. The live model canaries stay skipped: never set CODEX_REVIEW_RUN_CANARY or CLAUDE_REVIEW_RUN_CLAUDE_CANARY in CI.
  • .github/scripts/check_skill_frontmatter.py: every */skills/*/SKILL.md has YAML frontmatter whose name matches its directory and a non-empty description (needs PyYAML).

Run a suite locally the same way, e.g. cd tools/workspace-gc && python3.14 -m unittest discover -s tests -t . (the skill suites use discover -s tests from the skill directory). Use Python 3.11+ for the suites; CI uses 3.14. The three review CLI launchers accept python3 <skill>/bin/<review-loop> even with system Python 3.9: before importing the harness they select the newest working python3.1x on PATH (3.19 down to 3.10), or exit with a one-line prerequisite error.

The synthetic tmux sampler suite runs explicitly with cd codex/skills/tmux-transient-ui-verify && python3.14 -m unittest discover -s tests. It exercises both sampler copies without live panes or prompt sends. The workflow is unchanged under the owner’s no-new-Actions policy; run this suite locally.

Repo structure

agent-stuff/
  .github/              # CI workflow and its frontmatter check
  docs/
    review-cycle-log.md
    archive/            # closed log history
    specs/
    plans/
  codex/
    README.md
    skills/
      commit-workflow/
      cross-agent-review-cycle/
      goal-handoff/
      implement-handoff/
      claude-review-loop/
      opus-review-loop/  # legacy compatibility shim
      review-handoff/
      work-ledger/       # shared by Codex, Claude and Pi
      multi-agent-coordination/  # shared by Codex, Claude and Pi
  claude/
    README.md
    skills/
      goal-handoff/
      handoff-impl/
      handoff-review/
      pi-review-loop/
      codex-review-loop/
    commands/
      cmsg.md
  pi/
    README.md
    skills/
      commit-ready/
      commit-workflow/
      review-handoff/
  tools/
    workspace-gc/       # agent-neutral CLI, not a skill; run from this checkout
    guard-projects/     # opt-in PreToolUse hook and pre-push owner check
    claude-usage-read/  # weekly Claude usage via `claude -p /usage`, optional work report
    pane-watchdog/      # read-only herdr pane scan for dialogs, questions, typed input
  README.md

Each agent directory has its own README with agent-specific details (what stays private, install constraints). Skills may include supporting files beyond SKILL.md — for example, pi/skills/review-handoff/scripts/gather-changes.sh.

How skills get installed

Skills are installed via chezmoi symlinks. The dotfiles repo (~/.local/share/chezmoi) handles two things:

1. Cloning this repo via .chezmoiexternal.toml:

["projects/agent-stuff"]
    type = "git-repo"
    url = "git@github.com:ephes/agent-stuff.git"
    refreshPeriod = "168h"

This clones the repo on first chezmoi apply and pulls updates weekly. chezmoi processes external entries before deploying managed files, so the repo is guaranteed to exist before symlinks are created.

2. Creating symlinks via templates like:

# Example: dot_claude/skills/symlink_handoff-impl.tmpl
{{ .chezmoi.homeDir }}/projects/agent-stuff/claude/skills/handoff-impl

Most skills are path-agnostic, and the concrete clone path is normally a dotfiles-level choice. The shared Claude review workflow is the explicit current exception: its Codex/Claude skill instructions resolve the authoritative harness and review log under ~/projects/agent-stuff. Install this repository at that path, or update those shared-workflow references together when deploying it elsewhere.

Adding or updating a skill

  1. Create or edit the skill under the appropriate agent directory (e.g., claude/skills/my-skill/SKILL.md)
  2. If this is a new skill, add a symlink template to the dotfiles repo (e.g., dot_claude/skills/symlink_my-skill.tmpl)
  3. Run chezmoi apply
  4. Update the agent's README and the skill inventory table above

Similar skills across agents are intentionally kept separate so each version can be tuned to its agent's model, tool names, and interaction patterns. The exception is cross-agent-review-cycle: it is agent-neutral policy, and keeping two copies let them drift into contradictory stopping rules, so every agent symlinks the single copy under codex/skills/. work-ledger follows the same rule: it describes a shared data contract, not agent mechanics, and so does multi-agent-coordination, which is coordination policy.

Handoff review consistency

Implementation and review handoffs carry the canonical value-driven stopping policy, cumulative finding dispositions, and scoped repair context into fresh sessions. Implementation-only workers leave review to the independent driver; explicit end-to-end ownership permits installed review harnesses. Advisory closure is reported as advisory, and failed attempts never count as reviews. Synthetic behavioral forward checks are in docs/fixtures/handoff-review/requests.md.

The canonical policy, handoffs and pi-review-loop all require Pi openai-codex/gpt-6.1-sol, the model pinned for both review harnesses on 2026-09-30. A required Pi gate needs Pi's OpenAI Codex subscription login; when that login or the model is unavailable the gate is blocked, without a model/provider substitution. The implementer tier keeps gpt-6-sol.

Workflow lessons

Reusable agent/process lessons live in docs/review-cycle-log.md. Use it for things that should improve future skills, goal prompts, tmux orchestration, or cross-agent review mechanics across projects. Project-specific execution lessons belong in that project's own docs, and per-run metrics belong nowhere.

Every entry ends with a Promotion: line naming the skill and section that now carries the rule, or pending with what is still missing. Promoting the lesson is part of closing the cycle, not a later cleanup pass: grep '^- Promotion: pending' docs/review-cycle-log.md is the backlog.

Append the lesson and commit+push it immediately in its own small commit (fetch/rebase first); never leave the log uncommitted.

Closed history lives in docs/archive/.

Design decisions

Per-agent skills, not shared — except shared policy. The 10-30% that differs between agents is prompt engineering tuned to each agent's model and tooling. A shared template system is not worth the complexity. But a skill that encodes gate policy rather than agent mechanics gets exactly one copy that every agent symlinks: duplicating cross-agent-review-cycle produced a Claude copy with a hard three-cycle cap and a Codex copy with value-driven stopping, and the review loop's behavior then depended on which file the session happened to load.

Not every agent needs every skill. Skills exist only where they are useful. No gap-filling for symmetry.

Chezmoi symlinks over alternatives. Chosen over --add-dir (Claude Code only), plugins (overkill for personal use), rsync scripts, and git submodules. One mechanism across all agents.

.chezmoiexternal.toml for bootstrap. Declarative, handles both initial clone and periodic updates, and guarantees ordering (repo exists before symlinks are created).

When to revisit this structure

  • Substantial duplication across agents causes real maintenance pain
  • A new coding agent is added and the per-agent pattern does not scale
  • Chezmoi symlinks hit reliability issues
  • The Agent Skills spec matures enough for a cross-tool shared format
Ver o original no GitHub

Bom para

Relacionados