My Agent Config
arvindbattula/my-agent-config
Skills e workflows de engenharia para Claude Code, sincronizados entre máquinas
Ver no GitHubRepositório de configuração pessoal para sincronizar skills, comandos e regras do Claude Code entre máquinas. Inclui 18+ skills prontas para automação de workflows de engenharia (TDD, design, debugging, segurança) e 9 comandos estruturados para orquestração de projetos do zero ao deployment.
Instalação
npx convez-ai arvindbattula/my-agent-config1 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
Casos de uso
- Padronizar workflows de desenvolvimento em equipes ou múltiplos dispositivos
- Automatizar checklist de testes, segurança e design em projetos
- Estruturar fluxo de ideação→blueprint→construção→ship com comandos reutilizáveis
Veredito

Config pessoal madura e bem documentada, com foco em engenharia robusta (TDD, contract-first APIs, security). Útil para equipes que querem replicar padrões, mas requer customização para contextos diferentes — é um template, não uma ferramenta plug-and-play.
README
A tradução para o português deste README ainda está na fila.
my-agent-config
Personal agent configuration — skills, commands, rules, and settings — synced across machines. Primary target is Claude Code (~/.claude); skills and extensions are also synced for the Pi coding agent, and Codex reads AGENTS.md directly.
Quick Start
# On a new machine
git clone https://github.com/arvindbattula/my-agent-config.git
cd my-agent-config
./install.sh --force
# Check sync status anytime
./install.sh --status
# Preview changes without modifying anything
./install.sh --dry-run
What's Inside
Skills (auto-triggered by Claude)
| Skill | Purpose |
|---|---|
plan-build-verify | Workflow orchestration — plan, build, and verify complex coding tasks |
test-first | Test-driven development with red-green-refactor and Prove-It bug fix pattern |
research | Convergence-driven research with adversarial verification — tiered multi-engine search, iterative synthesis, claim challenging, cited briefs |
security | OWASP Top 10 prevention, input validation, secrets management, npm audit triage |
debugging | Systematic root-cause debugging — Stop-the-Line rule, 6-step triage checklist |
api-contracts | Contract-first API design, error semantics, REST patterns, validation at boundaries |
git | Trunk-based development, atomic commits, save-point pattern, git bisect |
performance | Measurement-first optimization, Core Web Vitals, N+1 prevention, bundle budgets |
react-engineering | React component architecture, state management, file structure discipline |
design-setup | Design principles, anti-patterns, OKLCH color theory, typography — run /design-setup teach once per project |
design-review | Scored design quality audit (accessibility, theming, responsive, anti-patterns) with P0-P3 severity |
design-polish | Final-pass design refinement — alignment, spacing, interaction states, micro-details |
design-typography | Typography assessment and fixes — font selection, hierarchy, readability, scales |
dead-code | Find and remove unused files, deps, exports via knip |
triage | Investigate bugs, find root cause, create issue with TDD fix plan |
diagram | Render inline interactive visuals — SVG diagrams, HTML widgets, charts |
electron-wrapper | Wrap a web app into an Electron desktop app |
read-the-damn-docs | Web-search for current official docs before implementing external packages, APIs, or version-sensitive behavior. Prevents guessing from stale model memory. Includes memory feedback loop for documenting quirks. |
Commands (user-invoked via /)
Workflow — Structured AI-assisted engineering:
/idea-refine → /scaffold → /discover → /blueprint → /construct → /inspect → /ship → /production-gate → /retro
↑ |
└──────────────┘
(loop until done)
| Command | Purpose |
|---|---|
/idea-refine | Divergent→convergent thinking to sharpen fuzzy ideas into buildable concepts |
/scaffold | Bootstrap CLAUDE.md + docs/ directory for any new project |
/discover | Structured product interview (scales by project size) → writes spec.md. Reads engineering patterns and blind spots from past projects. Includes EARS requirements, boundaries, and spec self-audit. |
/blueprint | Break spec into phased build plan → writes plan.md. Orientation step checks existing code. Cross-checks phase integration. Reads engineering patterns. |
/construct | Execute one phase at a time. Orientation step scopes changes. Resumes partial work. Live spec reconciliation when gaps found. Context window management. |
/inspect | Multi-pass review (architecture, spec compliance, edge cases, code quality, security). Severity labels, dependency review, change sizing guidance. |
/ship | Pre-launch checklist (code quality, security, performance, infrastructure, docs). Rollback plan template and post-deploy verification. |
/production-gate | Go/no-go gate to promote a vibe-coded prototype into a managed IT environment. Applicability triage, sectioned readiness checklist (owner + [Claude High/Partial/None] + blocker/waiver markers), waiver mechanism, sign-off table. |
/decide | Log architecture/product decisions in ADR format → decisions.md |
/retro | Project retrospective — extracts blind spots, positive patterns, and skill performance notes. Feeds back into all workflow skills. |
Use /decide anytime during the workflow. Run /retro at milestones or when a project ships — it makes the entire workflow smarter by learning from each project.
Self-improving workflow: Each workflow command has a ## Performance Notes section that /retro populates with dated, evidence-backed observations. Patterns validated across 3+ projects get proposed as actual skill instruction changes. Positive engineering patterns (validated tech choices, architectural approaches) persist in auto-memory and feed into /discover and /blueprint.
Utility commands:
| Command | Purpose |
|---|---|
/push-further | Challenge Claude to find the boldest addition to the current plan |
/cleanup-ai-slop | Remove AI-generated cruft from the current branch |
/code-simplify | Simplify recently changed code for clarity |
/organize-claude-config | Refactor CLAUDE.md for progressive disclosure |
/grill-me | Relentlessly interview you about a plan until all decisions are resolved |
/review-architecture | Find architectural improvements by deepening shallow modules |
/sync | Compare repo vs local config and resolve differences |
/wrap-session | End-of-session routine. Routes session learnings (preferences, references, in-flight state) to auto-memory, docs/state.md, or CLAUDE.md. Review-before-write, size-capped. |
Rules (always-on)
| Rule | Behavior |
|---|---|
verify-before-done | Always verify work before declaring complete; frontend requires tests + lint + build |
no-ai-slop | No obvious comments, no unnecessary defensive checks, no aspirational comments describing unimplemented intent |
simplicity-over-cleverness | Simplest solution that works, no over-engineering |
tdd-is-not-universal | Gate strict test-first on spec stability, code longevity, and testable surface; build-first + verify-after when any gate fails |
ask-dont-assume | Ask on ambiguous tasks; use judgment on minor reversible decisions |
minimal-diff | Only change what's necessary; exception: update broken call sites directly |
sunk-cost-breaker | Stop after 3+ failed attempts; propose fresh restart with lessons learned |
no-lint-suppression | Fix lint/type errors, never suppress with eslint-disable or ts-ignore |
no-backwards-compat | No migration shims or compatibility wrappers unless explicitly asked |
enumerate-spec-lists-first | Split slash-lists and conditional clauses in specs into enumerated items before implementing |
tests-enforce-spec-not-code | Every test assertion should trace to a spec requirement, not incidental implementation |
test-every-escape-hatch | For every test bypass (dry-run, mock, skip flag), write one smoke test that uses the real path |
async-writes-serialize | Serialize concurrent async writes to shared state via a single-flight queue |
batch-loop-exception-breadth | Use broad except Exception per item in batch loops calling external services |
like-wildcard-escaping | Escape %, _, \ in SQL LIKE with user input, even when parameterized |
path-containment-after-regex | Pair regex path gates with segment check + post-resolve containment (and realpath for symlink threats) |
no-unsourced-claims | Never invent stats; tag quantitative claims as sourced/estimate/opinion; don't smuggle opinions as facts |
skill-completion-receipt | For 2+ step skills/commands, print a per-step receipt (✓/✗/N/A) before claiming done |
check-docs-first | For external libraries and APIs, check memory, then current docs; save non-obvious quirks to memory |
keep-going-when-clear | When the next step is clear, keep going instead of stopping to report or offer; still stop when ambiguous or destructive |
verify-edit-batches | After a multi-edit batch, diff against a backup and count hunks before claiming success |
Hooks
| Hook | Trigger | Purpose |
|---|---|---|
session-start.sh | SessionStart | Brief workflow reminder injected at session start |
compress-memory.sh | PostToolUse → Write | Auto-compress prose in memory files (filler removal, phrase shortening). Preserves frontmatter, code, URLs, paths. Validates before writing, restores on corruption. |
design-antipattern-check.sh | PostToolUse → Edit/Write | Detects AI design anti-patterns (Inter font, purple gradients, side-stripe borders, gradient text, #000/#fff, HSL) in frontend files and warns inline. Records failures in .hook-state/last_design_gate.json at the project root for stop-gate.sh |
design-antipattern-prevent.sh | PreToolUse → Edit/Write | Blocks design anti-patterns in frontend files before they reach disk; the post-write check and stop gate remain as a backstop |
protect-paths.sh | PreToolUse → Edit/Write | Blocks edits to .env and .env.* files and .git at any depth, generated/ at the project root, and paths outside the project (except the Claude scratchpad, plan files, and auto-memory). The project is cwd, plus CLAUDE_PROJECT_DIR when it's an absolute path, so a Bash cd doesn't lock you out of the repo. Fails closed if jq is missing or the payload is unreadable. |
command-policy.sh | PreToolUse → Bash | Conservative denylist: blocks rm -rf on root/home/cwd/parent, DROP/TRUNCATE TABLE, reading .env files with cat, less, more, tail or head (within one command; grep, sed and others aren't covered), and force-pushes to main/master; scoped rm -rf and force-pushes to feature branches stay allowed |
stop-gate.sh | Stop | Blocks completion once while the current session's design gate still lists failing files, then lets the retry finish to avoid a loop. Uses the same project root as design-antipattern-check.sh; gates from earlier sessions are ignored |
session-end.sh | SessionEnd | Appends a JSONL audit record to reports/session-audit.log at the project root; always exits 0 |
design-checks-lib.sh holds the checks shared by both design hooks. hooks.test.sh is the test suite.
Config
settings.json— Permissions, hooks, extended thinking, plugins, statuslinestatusline.sh— Terminal status bar showing directory, model, context usage, git state (Claude Code)pi/extensions/statusline.ts— Equivalent two-line footer for the Pi coding agent, synced to~/.pi/agent/extensions/byinstall.sh(auto-discovered by the Pi CLI). Shows model, dir, git branch + diff stats, thinking level, context bar, tokens, cost, and session elapsed time. Rate limits are omitted (not exposed by Pi); duration is session wall-clock rather than cumulative request time. Colors usetheme.fg(), so the footer adapts to the active Pi theme.
Light terminal: Pi auto-detects terminal background; if it guesses wrong (e.g. a dark theme on a white terminal), text becomes unreadable. Set
"theme": "light"in your personal~/.pi/agent/settings.json— this is machine/terminal-specific and intentionally not committed.
Pi Coding Agent
The Pi CLI defaults to the Valar provider, zai-org/GLM-5.3 (pi/settings.json), running on the standard completion window — the tier pi/models.json cost fields are priced against. Valar bills omitted-window requests at the highest (Now) tier, so valar-completion-window.ts injects metadata.completion_window on every Valar request (ADR-010).
Key extensions (all synced to ~/.pi/agent/extensions/ by install.sh; per-extension detail in pi/extensions/README.md):
valar-completion-window.ts— injects the completion window on every Valar request, and registers the/valarcommand: interactive picker (window + thinking level) or direct args —/valar <window> [level](e.g./valar priority high);now→asap,none→off aliases; session-only, new sessions default tostandard(ADR-013)plan-mode/— verified plan execution (harness-checked[Verify:]steps, kernel sandbox on macOS/Linux; under agent-safehouse it degrades to the regex guardrail with one explained warning, ADR-011). Typechecked vianpm run check(tsc --noEmit+ SDK stubs), enforced by CI on PRs (ADR-014)questionnaire.ts— the multi-tab select tool plan mode relies onstatusline.ts— two-line footer (above)azure-*.ts— Azure Foundry / OpenAI provider extensions with their own retry loopverify-valar-window.mjs,*.test.mjs— smoke/test suite; runnode pi/extensions/*.test.mjsand the verify scripts after every pi update
How Sync Works
install.sh compares the repo and ~/.claude/ using file checksums:
✓Identical — no action needed↓In repo, not local — copies to local↑Local has changes — warns before overwriting+Local only — prompts to copy to repo~Both exist, differ — lets you choose which to keep
All overwrites create timestamped backups in ~/.claude/backups/.
Beyond ~/.claude/, install.sh also syncs Pi coding agent resources when present:
- Pi skills (
~/.agents/skills) — repo skills are symlinked;/-commands are generated intosource-command-*skills. - Pi extensions (
~/.pi/agent/extensions) — all repopi/extensions/files are copied there recursively (auto-discovered by the Pi CLI). Personal extensions not in the repo (e.g.valar-strip-reasoning.ts) show as+ local onlyand are never pulled in automatically. - Pi extension dependencies —
npm ciinstalls plan-mode's sandbox runtime. - Pi config (
~/.pi/agent) —pi/models.jsonandpi/settings.jsonare synced.--forceoverwrites the live files, so set the default model in the repo.
The skills step only runs if ~/.agents exists; the other Pi steps only run if ~/.pi/agent exists.
Note: A running Claude Code session manages
~/.claude/settings.jsonin memory and may overwrite external changes. Ifsettings.jsonshows as "differs" after sync, exit all Claude Code sessions first, then run./install.shagain.
Contributing
mainis protected — all changes require a PR, including the owner (no admin bypass)- PRs from non-collaborators are auto-closed
- Direct pushes to
mainare rejected server-side and flagged via GitHub Actions - Agents prepare PRs; merging is the owner's action — an agent may branch, commit, run checks, and (when asked) push + open a PR, but must never merge, revert, or delete merged branches autonomously (
/shipis the owner's phase;rules/ask-dont-assume.md)
Origin
Skills originally ported from brianlovin/agent-config and mattpocock/skills, renamed for clarity, reorganized into skills vs commands, and extended with custom rules.
Security, debugging, API design, git workflow, performance, frontend UI, and shipping skills adapted from addyosmani/agent-skills — a production-grade engineering skills library for AI coding agents. Anti-rationalization tables and red flags patterns also drawn from that project.
Design skills (design-setup, design-review, design-polish, design-typography) and the anti-pattern detection hook adapted from pbakaus/impeccable (Apache 2.0) — a design skill system that teaches AI coding assistants real design principles.
read-the-damn-docs skill adapted from BuilderIO/skills — extended with memory-first lookup and discovery feedback loop.