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 in current dir + config into ~/.codex
./install.sh agents          # → full practices bundle as AGENTS.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 and init produce two different files for two different jobs. agents drops the whole bundle as AGENTS.md, a portable reference manual. 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 at your root and copy targets/codex/{config.toml,agents,prompts} into ~/.codex; every other AGENTS.md-aware agent needs only that one file at your repo root.

What's inside

AGENTS.md is the universal layer: principles, the agent roster, the skills, and the full 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 (AGENTS.md, config.toml, agents/*.toml, 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 rules inlined in AGENTS.md already.) Install is a plain file copy: no hooks, no daemons, nothing running.

Project context layers

The committed AGENTS.md in this repo is a reference manual: the full bundle, flattened into one file for agents that can only read one file. A consuming project's AGENTS.md should be the opposite, kept thin. 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 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 + 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.