coding-agent-workflows

Coding standards, agent roles, skills, and multi-step workflows that read the same whether you drive Claude Code, Codex, Amp, or anything that reads an AGENTS.md. One neutral source produces a native config for each agent, and the agent-specific pieces stay scoped to the agents that need them.

Everything here is pre-rendered and committed. There is no build step to run before you use it.

Install

git clone https://github.com/sjarmak/coding-agent-workflows.git
cd coding-agent-workflows

Install for your agent:

./install.sh claude          # → ./.claude  (project-level; use `./install.sh claude ~` for user-level)
./install.sh codex           # → AGENTS.md + AGENTS.full.md in current dir + config into ~/.codex
./install.sh agents          # → AGENTS.md (thin index) + AGENTS.full.md (Amp, Aider, Gemini CLI, …)
./install.sh init            # → a thin, project-specific AGENTS.md (intention + pointers)

Pass a destination as the second argument to target a specific project, for example ./install.sh claude ~/work/myrepo.

AGENTS.md is deliberately thin: a ~80-line index that agents auto-load, pointing by section into AGENTS.full.md, the full bundle read on demand. The agent pulls in only the section a task needs, and the always-loaded context stays small. For an agent that can only ever read one file, copy AGENTS.full.md as its AGENTS.md instead.

agents and init produce files for two different jobs. agents drops the practices bundle (index + full text). init scaffolds a thin, per-project AGENTS.md that holds only this repo's intention and failure-mode preventions and points to the bundle for everything else. See Project context layers below.

If you would rather not run a script, copy what you need: Claude Code reads a .claude/ directory, so copy targets/claude/{rules,agents,skills,commands} into one; Codex reads an AGENTS.md at the repo root plus ~/.codex, so put AGENTS.md + AGENTS.full.md at your root and copy targets/codex/{config.toml,agents,prompts} into ~/.codex; every other AGENTS.md-aware agent needs just those two files at your repo root.

What's inside

The universal layer is two files: AGENTS.md, the thin always-loaded index, and AGENTS.full.md, the full text it points into — principles, the agent roster, the skills, and the workflows, written as prose any agent can follow. targets/claude/ is the native Claude Code layout (rules/, agents/, skills/, commands/). targets/codex/ is the native Codex layout (the same two AGENTS files, config.toml, agents/ with a toml plus full role instructions per agent, prompts/).

The rules are the best-practice layer: architecture, coding style, testing, security, git and development workflow, performance, context layering, task management, skill management, anti-slop, and the augmented-coding-patterns catalog, plus language specifics for Go, Python, TypeScript, and Rust. The agents, skills, and workflows operationalize them; the coding-practices skill indexes the rules in full.

Claude Code auto-discovers skills, agents, and commands, but does not auto-load rules/. Nothing is forced into your context on install: the coding-practices skill is a generated index that lets an agent discover the rules and read only the one it needs, on demand. (AGENTS.md-based agents get the same on-demand shape via the AGENTS.md index over AGENTS.full.md.) Install is a plain file copy: no hooks, no daemons, nothing running.

Project context layers

The bundle's AGENTS.md is a thin index over AGENTS.full.md, the reference manual. A consuming project's own AGENTS.md is kept thin for the same reason: nothing bulky lives in an always-loaded file. install.sh init plus the project-init workflow set up four layers, each owning one kind of knowledge so no fact is stored twice:

• Bundle — universal practices, agents, skills, workflows. Installed once, referenced everywhere.
• AGENTS.md (per project, thin) — this repo's intention and failure-mode preventions, plus pointers to the rest. Target ~120 lines.
• Compass files (COMPASS.md per area) — the tribal knowledge: the why, the gotchas, how an area connects. Generated by project-compass, kept fresh with a content-hash, indexed (not duplicated) by AGENTS.md.
• Memory (CLAUDE.md, instincts) — host- and session-specific state, left to the agent's own memory system.

Maintenance is explicit, not automated: failure-mode-capture appends a prevention to AGENTS.md (deduping against memory first), and project-compass refreshes a map when an area changes. The boundary rules live in the context-layering practice. The codebase-compass idea follows Meta's work on mapping tribal knowledge in large-scale pipelines.

The workflows encode the process

Each workflow is a multi-step procedure that composes the skills into a repeatable sequence an agent runs the same way every time:

• implement-review: plan, execute, simplify, then review as a hard gate before finalizing.
• research: diverge across angles, converge to a recommendation, pre-mortem it.
• brainstorm-loop: generate shape-distinct ideas, pre-mortem the frontrunners, converge.
• decompose: split large work into independently-reviewable units.
• epic-review: review the assembled whole at the integration boundary.

The review-as-a-gate step in implement-review is the load-bearing one: the agent that wrote the code checks the diff against the acceptance criteria, with authority to reject and retry from a fresh context.

Two kinds of slop, two separate guards

"Slop" means two different things here, and they never share a tool. Code slop is erosion and bloat in a diff; writing slop is AI tells in prose. Reach for the guard that matches what you're checking:

• Code slop → the slop-check skill scores a diff for erosion (dead branches and redundant structure that accrue as code is extended) and verbosity, mirroring the SlopCodeBench judge rubric; the same rubric backs the anti-slop rule (source/rules/common/anti-slop.md) and the slop pass in the code-reviewer agent and review skill.
• Writing slop → the writing-voice skill guards prose and docs (articles, blog posts, READMEs) against telltale AI writing patterns and adds positive craft defaults. A README is prose, not code, so it routes here, not to slop-check.

Separately, the caveman skill cuts conversational token use ~75% while preserving technical accuracy.

These pair well with CodeGraph, a local pre-indexed code knowledge graph (CLI + MCP) that cuts exploration tokens and tool calls; orthogonal to the guards above, but the same goal: less slop, fewer tokens.

Recommended companion tools (non-invasive)

Two rules point at external tools chosen for the reason the bundle is: they add capability without installing themselves into everything.

• skillager (the skill-management rule) is a local CLI that discovers, vets, and exposes agent skills on demand. You search skills by metadata and load only the few a task needs, rather than every skill in every chat. Installed once as a user tool (uv tool install skillager), nothing runs in the background, and it discovers the skills this bundle ships. Source: github.com/jarmak-personal/skillager.
• beads_rust (the task-management rule) is a dependency-aware task store frozen at a SQLite + JSONL architecture: no Dolt dependency, no auto-installed git hooks. The fuller beads adds a Dolt backend for versioned, multiplayer sync when a project actually needs it.

Both follow the rule the bundle preaches: take the lightest thing that solves the problem, and add weight only when a concrete need appears.

Provenance & license

MIT. Derived from Everything Claude Code (MIT, Affaan Mustafa); the augmented-coding-patterns rule synthesizes the Augmented Coding Patterns catalog; the anti-slop rule and slop-check skill adapt the code-erosion rubric from SlopCodeBench (SprocketLab/slop-code-bench). See NOTICE.

---

Maintainer notes (you don't need these to use the repo)

The committed AGENTS.md, AGENTS.full.md, and targets/ are generated from source/, the only hand-edited layer. To change the bundle, edit source/ and run:

npm run build      # regenerate AGENTS.md + AGENTS.full.md + targets/ from source/
npm run sanitize   # release gate: scan rendered output for paths, PII, internal jargon
npm run release    # build + sanitize
npm run check      # CI: fail if committed output drifted from source/

source/manifest.json is the scope map (universal, claude, or codex) that decides where each artifact renders. rule_overrides marks an individual rule file such as hooks.md as Claude-only, so it ships to targets/claude/ but stays out of the universal layer. The templates section lists project-scaffolding files (AGENTS.project.md, COMPASS.md) that ship verbatim into each target's templates/ dir and are excluded from the universal AGENTS.md prose.