Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
106 lines (72 loc) · 3.13 KB

CONTRIBUTING.md

File metadata and controls

106 lines (72 loc) · 3.13 KB

Contributing to retort

Guidelines for contributing to this project, including both human and AI-assisted development workflows.

Table of Contents

  1. Getting Started
  2. Development Workflow
  3. Commit Conventions
  4. Pull Request Process
  5. AI Agent Contributions
  6. Code Standards

Getting Started

  1. Fork and clone the repository
  2. Install dependencies for your stack (see agentkit discover output)
  3. Run retort sync to generate AI tool configurations
  4. Create a feature branch from main

Development Workflow

This project follows a 5-phase lifecycle model:

  1. Discovery — Understand the problem, review existing docs
  2. Planning — Design the solution, write ADRs for significant decisions
  3. Implementation — Write code, add tests, run /check locally
  4. Validation — Create PR, pass CI, get code review
  5. Ship — Merge, update changelog, monitor deployment

See UNIFIED_AGENT_TEAMS.md for full details.

Commit Conventions

Use Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, test, chore, ci, perf

Examples:

  • feat(api): add user registration endpoint
  • fix(auth): handle expired token refresh
  • docs(readme): update setup instructions
  • chore(deps): update vitest to v2.1

Pull Request Process

  1. Ensure your branch is up to date with main
  2. Run all quality gates locally: retort validate
  3. If you changed .agentkit/spec/*.yaml, run pnpm --dir .agentkit retort:sync and commit the regenerated outputs
  4. Create a PR — title MUST use Conventional Commits format: type(scope): description
    • Example: feat(auth): add OAuth2 login flow — NOT Plan: Add OAuth2 login flow
    • CI enforces this and will reject non-conforming titles
  5. All CI checks must pass (including drift check for generated files)
  6. Request review from the relevant team (see UNIFIED_AGENT_TEAMS.md)
  7. Address review feedback
  8. Squash-merge when approved

AI Agent Contributions

When using AI agents (Claude Code, Cursor, Copilot, etc.):

  • Generated configuration files (marked GENERATED by Retort) should not be edited directly — modify the spec and run retort sync instead
  • Use /orchestrate for multi-team coordination tasks
  • Use /check to validate changes before committing
  • AI agents operate within the permission model defined in .claude/settings.json
  • Hook scripts provide guardrails against destructive actions

Code Standards

Code standards are defined per tech stack in .agentkit/spec/rules.yaml. Key conventions:

  • Follow the linting and formatting rules for your language
  • Write tests for new functionality
  • Document public APIs
  • Keep changes small and focused
  • No hardcoded secrets or credentials

This guide is maintained by Retort. Run pnpm --dir .agentkit retort:sync to regenerate.