Home | Installation and Setup | API Reference | Contributing

This page outlines the development guidelines, coding standards, and workflows for contributing to the AICollaborator project. These guidelines ensure consistent, high-quality code and smooth collaboration between human developers and AI agents.

1. Coding Standards
2. Development Environment
3. Development Workflow
4. Branching Strategy
5. Version Control Practices
6. Code Review Process
7. AI-Specific Development Guidelines
8. Machine-Readable Guidelines

AICollaborator follows the Swift API Design Guidelines and enforces additional project-specific standards:

• Quality First: Focus on delivering high-quality, well-tested code
• Clarity: Write clear, self-explanatory code and documentation
• Compatibility: Ensure code works on macOS 15+ with Swift 6
• Incremental Changes: Prefer smaller, focused PRs over large changes

• Use Swift's strong type system effectively; avoid force unwrapping optionals
• Follow Swift naming conventions (camelCase for variables/functions, PascalCase for types)
• Use extensions to organize code logically
• Prefer structs over classes for immutable data structures
• Use proper access control modifiers (private, fileprivate, internal, public)
• Utilize Swift's functional programming features where appropriate

• All public APIs must have Swift-style documentation comments (///)
• Include parameter descriptions, return values, and throws clauses
• Add usage examples for complex functionality
• Comment non-obvious code with inline explanations

• Use SwiftFormat to maintain consistent code style
• Set indentation to 4 spaces
• Max line length of 100 characters
• Use blank lines to group related code logically

1. Install required tools:

   xcode-select --install

2. Set up environment variables:

   export GEMINI_API_KEY="your_api_key_here"

3. Install additional dependencies:

   brew install gh

• IDE: Xcode 16+
• Terminal: iTerm2 with Zsh
• Version Control: Git with GitHub CLI
• Swift Package Management: Swift Package Manager
• Documentation: DocC
• Code Quality: SwiftLint, SwiftFormat

# Clone repository
git clone [email protected]:noktirnal42/AICollaborator.git
cd AICollaborator

# Set up dependencies
swift package resolve

# Build the project
swift build

# Run tests
swift test

1. Find or Create an Issue

   • Check existing issues before creating a new one
   • Use descriptive titles and detailed descriptions
   • Tag issues appropriately

2. Local Development

   • Create a feature branch from dev
   • Implement changes following coding standards
   • Run tests locally to verify changes

3. Testing

   • Write unit tests for new functionality
   • Ensure all tests pass before submitting a PR
   • Aim for high code coverage

4. Submission

   • Create a pull request to the dev branch
   • Fill out the PR template completely
   • Request reviews from appropriate team members

5. Review and Iteration

   • Address feedback promptly
   • Make requested changes
   • Keep PR updated with latest changes from dev

6. Merge

   • Squash commits if appropriate
   • Merge to dev after approval
   • Delete feature branch after merge

AICollaborator uses a structured branching strategy:

• main: Production-ready code
• dev: Integration branch for upcoming releases
• feature/*: Feature development (e.g., feature/new-authentication)
• bugfix/*: Bug fixes (e.g., bugfix/login-crash)
• release/*: Release preparation (e.g., release/v1.2.0)
• hotfix/*: Critical fixes for production (e.g., hotfix/critical-security-issue)

<type>/<descriptor>

Where:

• <type> is one of: feature, bugfix, release, hotfix
• <descriptor> is a brief, hyphenated description of the change

Examples:

• feature/agent-orchestration
• bugfix/memory-leak
• release/v1.0.0

• Write clear, concise commit messages in imperative form
• Start with a capital letter and do not end with a period
• Keep commits focused on a single logical change
• Reference issue numbers in commit messages

<type>: <subject>

[optional body]

[optional footer]

Where:

• <type> is one of: feat, fix, docs, style, refactor, test, chore
• <subject> is a short description of the change

Example:

feat: Add multi-agent orchestration capability

Implements the ability to coordinate multiple AI agents with different
specializations to work together on complex tasks.

Closes #123

• Keep PRs focused on a single concern
• Include detailed descriptions of changes
• Link to relevant issues
• Add screenshots or videos for UI changes
• Respond promptly to review feedback

All code will be reviewed for:

1. Functionality: Does it work as intended?
2. Quality: Is the code well-structured and efficient?
3. Testing: Are tests comprehensive and passing?
4. Documentation: Are changes properly documented?
5. Compatibility: Does it maintain compatibility with required platforms?

• Human-authored PRs will be reviewed by at least one maintainer
• AI-authored PRs require review by at least two human maintainers
• Code owners will be automatically assigned based on modified files

• Initial review will be provided within 3 business days
• Contributors should respond to feedback within 5 business days
• PRs with no activity for 14 days may be closed

• AI agents should identify themselves in contributions
• Follow structured formats for code submissions
• Include reasoning and confidence levels
• Focus on maintainable, well-documented code

AI agents should format contributions as follows:

AI-CONTRIBUTOR: {model_identifier}
CONTRIBUTION-TYPE: {code|documentation|test|review}
RATIONALE: {concise explanation for changes}
CONFIDENCE: {high|medium|low}

• Humans should provide clear, structured instructions to AI contributors
• AI agents should clearly indicate reasoning and uncertainty
• Establish shared terminology and conventions
• Document AI-human collaboration patterns in the wiki

• AI-generated contributions should be reviewed by human maintainers
• AI agents should not modify critical security or authentication code without explicit human oversight
• When uncertain, AI agents should propose alternatives rather than single solutions

{
  "coding_standards": {
    "language": "Swift",
    "version": "6",
    "style_guides": [
      {
        "name": "Swift API Design Guidelines",
        "url": "https://swift.org/documentation/api-design-guidelines/"
      }
    ],
    "formatting": {
      "indentation": "4 spaces",
      "line_length": 100,
      "tools": ["SwiftFormat", "SwiftLint"]
    },
    "documentation": {
      "required_for": ["public APIs", "internal interfaces"],
      "format": "Swift-style comments (///)",
      "requirements": ["parameter descriptions", "return values", "examples for complex functionality"]
    }
  },
  "development_workflow": {
    "branching_strategy": {
      "main_branches": ["main", "dev"],
      "supporting_branches": ["feature/*", "bugfix/*", "release/*", "hotfix/*"],
      "default_development_branch": "dev",
      "production_branch": "main"
    },
    "commit_message_format": {
      "structure": "<type>: <subject>",
      "types": ["feat", "fix", "docs", "style", "refactor", "test", "chore"]
    },
    "review_process": {
      "required_approvals": {
        "human_authored": 1,
        "ai_authored": 2
      },
      "review_timeline_days": 3,
      "response_timeline_days": 5,
      "stale_pr_days": 14
    }
  },
  "ai_agent_guidelines": {
    "contribution_format": {
      "structure": "AI-CONTRIBUTOR: {model}\nCONTRIBUTION-TYPE: {type}\nRATIONALE: {reason}\nCONFIDENCE: {level}",
      "confidence_levels": ["high", "medium", "low"]
    },
    "limitations": [
      "Cannot modify security code without human oversight",
      "Must be reviewed by human maintainers",
      "Should propose alternatives when uncertain"
    ]
  }
}

• Swift API Design Guidelines
• Swift Language Guide
• GitHub Flow
• Testing with XCTest

For questions about these guidelines, please open a discussion on the GitHub repository.