Synorg keeps AI agents honest by forcing a GitHub-first, single-issue-at-a-time workflow. It auto-syncs real GitHub issues, prioritizes human-created work, assigns Copilot only when an issue is truly next, and creates post-merge and post-deploy verification tasks so nothing lands silently in production.

• Runaway agents & local edits: All work is done via GitHub issues/PRs; no local file writes.
• Backlog drift: We sync and prioritize existing GitHub issues before generating anything new.
• Too many concurrent threads: Only one issue is in progress; Copilot is assigned at promotion time.
• Unverified merges/deploys: Post-merge reviews (priority 10) and post-deploy verification tasks (priority 10) are auto-created; deploy failures raise fix_deploy (priority 9).

1. Backlog ingestion: Webhooks + scheduled sync create/refresh work_type: "issue" items from open GitHub issues (priority ≥ 9).
2. Single-issue sequencing: IssueSequencerJob picks the top pending issue (priority + created_at) and assigns Copilot when it flips to in_progress.
3. Agent execution: Agents emit GitHub operations (issue/branch/PR/files) and run remotely via GithubApiStrategy.
4. Safety nets:
   • Post-merge review work items (priority 10).
   • Post-deploy verification work items (priority 10) on successful deploy webhooks.
   • Deploy failures create fix_deploy work items (priority 9).
5. Visibility: UI surfaces “Next up” (highest-priority pending, ready, unlocked issue).

See the mermaid diagram: docs/workflows/ideal.md.

Prerequisites: Docker Desktop or Docker Engine with Docker Compose.

# 1. Clone the repository
git clone https://github.com/mitchellfyi/synorg.git
cd synorg

# 2. Copy and configure environment variables
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY (required for agents)

# 3. Build and start all services (postgres, web, worker)
docker compose up --build

# 4. In a new terminal, prepare the database
docker compose exec web bin/rails db:create
docker compose exec web bin/rails db:schema:load

# Note: Use db:schema:load instead of db:migrate for initial setup.
# Some migrations have pre-existing bugs with JSON vs JSONB column types
# that cause errors on fresh databases. This will be fixed in a future update.
# Once the schema is loaded, db:migrate will work for subsequent changes.

# 5. (Optional) Seed the database with initial data
docker compose exec web bin/rails db:seed

Open http://localhost:3000.

Common Docker commands:

# Start services in background
docker compose up -d

# View logs
docker compose logs -f web
docker compose logs -f worker

# Run migrations (if schema is up to date)
docker compose exec web bin/rails db:migrate

# Run tests
docker compose exec web bundle exec rspec

# Open Rails console
docker compose exec web bin/rails console

# Reset database
docker compose exec web bin/rails db:reset

# Rebuild images (after Gemfile/package.json changes)
docker compose build

# Stop all services
docker compose down

# Stop and remove volumes (destroys database data)
docker compose down -v

# Run any command in the web container
docker compose exec web <command>

Prerequisites:

• Ruby 3.4.2 (.ruby-version)
• Node.js 24.5.0 (.node-version, .nvmrc)
• PostgreSQL 16+
• Bundler 2.7+

bin/setup   # installs deps, db setup, hooks
bin/dev     # rails + worker + assets

Open http://localhost:3000.

• GitHub-first: Issues/PRs created via GitHub API; Copilot assigned on promotion to in_progress.
• Bidirectional sync: Internal work items automatically synced to GitHub issues; GitHub issues synced back as work items.
• PR lifecycle automation: Auto-assign reviewers, auto-merge on approval (configurable), post-merge verification.
• Priority model: Human/real GitHub issues ≥9; post-merge/deploy items =10; deploy-fix =9.
• One at a time: Sequencer + locks ensure only one issue is active; pump job keeps queue flowing.
• Remote-only: No local writes; agents operate through GitHub operations.
• Verification: Post-merge and post-deploy checks are mandatory tasks, not suggestions.

See full workflow documentation in docs/workflows/github-issue-pr-sync.md.

• Run app: bin/dev
• Tests: bin/test
• Lint/format/type/security: bin/lint, bin/format, bin/brakeman, bin/bundler-audit

Installed via Lefthook:

• Pre-commit: RuboCop, ERB Lint, ESLint, Prettier auto-fix staged files.
• Pre-push: full suite (lint + security + tests).

• Rails 8.1.1, Ruby 3.2.3, PostgreSQL, Solid Queue
• Frontend: Tailwind v4, TypeScript (esbuild), Hotwire (Turbo/Stimulus)
• Tests: RSpec
• Tooling: RuboCop, ERB Lint, ESLint (flat), Prettier, Brakeman, bundler-audit

GitHub Actions: lint (Ruby/ERB/JS/Prettier), type-check, Brakeman, bundler-audit, RSpec, Playwright smoke tests.
Required secret: RAILS_MASTER_KEY (Actions → Secrets → Actions).

app/       controllers, models, jobs, views, TS, assets
bin/       scripts (setup, dev, jobs, lint, test)
config/    Rails, Solid Queue, recurring schedules
docs/      architecture, workflows, agents
spec/      RSpec suite

1. Branch from main
2. Make changes
3. Run bin/lint and bin/test
4. Open PR (CI must pass)

All rights reserved.