Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
183 lines (136 loc) · 5.17 KB

CONTRIBUTING.md

File metadata and controls

183 lines (136 loc) · 5.17 KB
Raw

Contributing to AI Development Squad Template

Thank you for contributing. This is an open-source project licensed under AGPLv3.

What You Can Contribute

Area Examples
New agents Add a specialist for a new language, framework, or service
Improved agent prompts Sharpen existing agent instructions, tool restrictions, or escalation rules
New skills Add a SKILL.md for a tool or workflow not yet covered
New commands Add a /command.md for a common pipeline pattern
CLI improvements Improve scripts/ai-squad (new subcommands, UX, error handling)
Tests Add tests in tests/ for new or existing functionality
Documentation Improve README.md, ARTICLE.md, or agent descriptions
Bug fixes Fix incorrect model IDs, broken frontmatter, bad shell syntax

Getting Started

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/AI-Development-Squad-Template.git
cd AI-Development-Squad-Template

# 2. Install the CLI globally from your fork
echo 'export PATH="'$(pwd)'/scripts:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 3. Run the test suite to confirm everything passes
bash tests/run_all.sh

Repository Structure

.
├── scripts/
│   └── ai-squad              # Global CLI (init · labels · swarm)
├── template/                 # Everything copied on ai-squad init
│   ├── .claude/agents/       # 27 Claude Code agent definitions
│   ├── .claude/commands/     # 5 slash commands
│   ├── .claude/skills/       # 17 skill files
│   ├── .opencode/agents/     # 27 OpenCode agent definitions (mirrored)
│   ├── .opencode/commands/
│   ├── .opencode/skills/
│   ├── infra/scripts/        # seed-test.sh (called by make seed-test)
│   ├── Makefile
│   ├── CLAUDE.md
│   ├── AGENTS.md
│   └── opencode.json
├── tests/
│   ├── cli/                  # CLI tests
│   └── template/             # Template validation tests
└── .github/workflows/        # CI/CD

CI/CD

Every pull request runs:

Job What it checks
Lint shellcheck on all .sh files
CLI Tests ai-squad help, swarm help, init, file count assertions
Template Validation Structure, agent frontmatter, skills, commands
Model ID Audit No stale date-suffixed IDs; Orchestrator/Architect use Opus

The ci-gate job fails the PR if any of the above fail. PRs cannot be merged with a failing gate.

Adding an Agent

1. Claude Code (.claude/agents/{name}.md)

---
name: my-agent
description: One-line description shown in the agent picker.
model: claude-sonnet-4-6
---

You are a specialist agent in an orchestrated, phase-gated pipeline.

Hard rules:
- Only work on tasks assigned by @orchestrator.
- Never skip quality gates.
- Read relevant skills from `.claude/skills/` before executing tasks.
- After 3 consecutive failures, stop and report to human.

2. OpenCode (template/.opencode/agents/{name}.md)

---
description: One-line description.
mode: subagent
model: github-copilot/claude-sonnet-4.5
temperature: 0.2
tools:
  write: true
  edit: true
  bash: true
permission:
  edit: ask
  bash:
    "*": ask
    "make *": allow
    "git status*": allow
    "git diff*": allow
    "gh *": allow
  webfetch: deny
---

[Same body as Claude Code agent]

3. Register the agent

  • Add to permission.task list in template/.opencode/agents/orchestrator.md
  • Add a row to template/AGENTS.md
  • Update the agent count in README.md

4. Add a test

The test in tests/template/test_agents.sh validates frontmatter automatically for all agents. If your agent has special requirements, add an assertion there.

Model Assignment Rules

Role Claude Code OpenCode
Orchestrator, Architect claude-opus-4-6 anthropic/claude-opus-4-6
All implementation agents claude-sonnet-4-6 github-copilot/claude-sonnet-4.5
Kubernetes, Terraform, Docker claude-sonnet-4-6 copilot/gpt-4.1

Never use date-suffixed model IDs (e.g., claude-sonnet-4-20250514). The CI model audit will catch these.

Conventional Commits

feat:     new agent, skill, command, or CLI subcommand
fix:      bug fix in existing agent, script, or frontmatter
test:     new or updated test files
docs:     README, ARTICLE, CONTRIBUTING, or agent description
infra:    Makefile, docker-compose, GitHub Actions
chore:    dependency updates, formatting, renames

Pull Request Checklist

  • bash tests/run_all.sh passes locally
  • New agents have correct frontmatter on both platforms
  • No stale model IDs
  • shellcheck passes on any new/modified .sh files
  • CHANGELOG.md updated if user-visible change

Code of Conduct

Be direct, technical, and respectful. This project values correctness and clarity over quantity of output. Reviewers will prioritize correctness of agent prompts, model assignments, and CI behavior.

License

By contributing you agree your work will be licensed under AGPLv3.

Copyright (C) 2025 Kinn Coelho Juliao kinncj@protonmail.com