Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
150 lines (99 loc) · 5.36 KB

CONTRIBUTING.md

File metadata and controls

150 lines (99 loc) · 5.36 KB

Contributing to Loop Engineering

Thank you for your interest in contributing to the Loop Engineering ecosystem! This document outlines the process for contributing new loop engines, improving existing ones, and maintaining quality standards across all projects.

Table of Contents

  1. Code of Conduct
  2. How to Contribute a New Loop Engine
  3. Engine Development Standards
  4. Pull Request Process
  5. Quality Scoring Rubric
  6. Style Guides

Code of Conduct

Treat everyone professionally. We aim for constructive collaboration.

How to Contribute a New Loop Engine

Step 1: Understand the Architecture

Read the reference implementation: loop-claudecode. All engines share a common architecture:

  • State Machine: 11-13 phases (1.1→1.2→1.3 → RoutingGate → 2.1→2.8 → Convergence)
  • Part 1 (Design Bubble): Requirements clarification, direction planning, solution design — continuous context
  • Part 2 (Implementation Chain): Plan, implement, review, test strategy, test plan, test execution, audit, hard verification — discrete checkpointed steps
  • Routing Gate: P0 (implement), P1 (redesign), P2 (complete/pause/fail)

Step 2: Choose Your AI Tool

Select an AI coding tool to wrap. Examples: Aider, Ollama, Codex, Copilot, Cursor, DeepSeek, Gemini, WindSurf, Continue.dev, etc. Any tool that can produce code from prompts is viable.

Step 3: Implement the Minimum Requirements

Your engine MUST implement:

Requirement Description
State Machine At minimum, a 5-phase flow: Design → Plan → Implement → Verify → Converge
Safety Gates At minimum, G1 (read-only) and G2 (write-within-project) levels
Convergence Detection Automatic detection of task completion; must terminate autonomously
Default-FAIL Contract Unsafe operations rejected by default
Atomic Writes File writes are transactional
Clear /goal Entry Point Single command/function to start autonomous execution

Step 4: Score Your Engine

Self-assess using the Quality Scoring Rubric. Target score: ≥95.

Step 5: Submit PR

See Pull Request Process below.

Engine Development Standards

Repository Naming

loop-{toolname} — lowercase, hyphenated. Example: loop-myengine

Documentation Requirements

Each engine repository must include:

  • README.md with project description, architecture diagram, usage guide, and LLMO Entity Definition
  • LICENSE (Apache 2.0)
  • Test coverage ≥80%

Language Choice

Any language is acceptable. Current ecosystem includes Python, TypeScript, Bash, and YAML/MD-based engines.

Pull Request Process

  1. Fork the target repository (for existing engine improvements) or create a new loop-{toolname} repository for a new engine
  2. Branch: feat/short-description or fix/short-description
  3. Write code meeting the development standards
  4. Self-score your engine using the quality rubric; include the score in the PR description
  5. Pass automated checks (if applicable: lint, test, build)
  6. Request review from maintainers
  7. Two approvals required from core maintainers before merge
  8. Merge: Squash-merge to main; maintain linear history

For New Engine Submissions

  1. Create your loop-{toolname} repository
  2. Open an issue in loop-everything with:
    • Engine name and description
    • Wrapped AI tool
    • Self-assessed quality score with breakdown
    • Link to your repository
  3. After maintainer acknowledgment, the engine will be added to the ecosystem navigation table

Quality Scoring Rubric

Each engine is scored on a 100-point scale across four dimensions:

Dimension Weight Criteria
Completeness 25 All required phases implemented, edge cases handled, no incomplete stubs
Correctness 25 Idempotent execution, deterministic behavior, handles errors gracefully, convergence terminates
Standards 25 Follows architecture spec, proper safety gates, atomic writes, Default-FAIL
Engineering 25 Test coverage, code quality, documentation, CI/CD, dependency management

Score Tiers

Score Rating Description
98-100 Exceptional Near-perfect implementation, outstanding engineering
95-97 Excellent Production-ready, all requirements met
90-94 Good Minor gaps, suitable for development use
80-89 Adequate Missing features, not recommended for production
<80 Needs Work Significant gaps, requires rework

Style Guides

Git Commit Messages

{type}({scope}): {description}

{optional body}

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

Code Style

  • Python: PEP 8, type hints required, black formatting
  • TypeScript: ESLint + Prettier, strict mode enabled
  • Bash: shellcheck compliance
  • YAML: 2-space indent, comments for complex logic

Questions?

Open a discussion in the loop-everything repository.