Contributing to AgentSys

April 23, 2026 · View on GitHub

Approval Process

All PRs require approval from the repo owner (@avifenesh). There are no other maintainers.

PRs may receive AI-assisted reviews (Copilot, Claude, Gemini, Codex) at the owner's discretion. If you receive review comments, you must address ALL of them before merge - no exceptions.

What Matters Here

This is a plugin for OTHER projects - workflow automation for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro users.

Core Priorities (In Order)

User DX - Experience when using this plugin in external projects
Worry-free automation - Users trust the plugin to run autonomously
Token efficiency - Agents should be efficient, not verbose
Quality output - Code written by agents must be production-ready
Simplicity - Remove complexity that doesn't serve users

What To Avoid

Overengineering - No config systems nobody asked for
Internal tooling - Don't optimize for developing THIS repo
Complexity creep - Every abstraction must justify itself
Summary files - No *_AUDIT.md, *_SUMMARY.md - clutter

Before You Start

First-Time Setup

After cloning the repo, install git hooks manually:

npm install
npm run setup-hooks

The setup-hooks script installs the pre-push hook into your local .git/hooks/ (it runs preflight checks, an /enhance reminder, and release-tag validation). It does not run automatically on npm install - you must opt in.

Multi-File Changes

For changes touching multiple files, read the relevant checklist first:

Change Type	Checklist
New slash command	`checklists/new-command.md`
New agent	`checklists/new-agent.md`
New lib module	`checklists/new-lib-module.md`

Library Architecture

lib/ is the canonical source. Plugins get copies.

# Edit in lib/
vim lib/patterns/pipeline.js

# Plugins are now standalone repos under agent-sh org.
# lib/ syncs to all plugin repos via agent-core CI pipeline.
# After merging lib/ changes here, agent-core propagates to plugins automatically.

Adapter Generation

Platform adapters (adapters/opencode/, adapters/codex/) are auto-generated from plugin source. Files with AUTO-GENERATED headers must not be manually edited.

After changing plugins, regenerate adapters:

npm run gen-adapters
# Or: npx agentsys-dev gen-adapters

CI validates adapter freshness on every push.

Pull Request Process

1. Create PR

git checkout -b feature/your-change
# make changes
npm test
git add -A && git commit -m "feat(scope): description"
git push -u origin feature/your-change
gh pr create --base main