Workflows, branching & CI/CD

1. Delivery workflow
2. Branching models
3. Autonomous work: the Ralph loop
4. CI/CD for the aiflow repo
5. Building locally the same way CI does

---

Delivery workflow

Issue (GitHub / GitLab / Bitbucket / …)
  └─ /intake-issue ─▶ Beads tasks (with acceptance criteria)
       └─ /decompose (task-master) ─▶ subtasks + dependencies
            └─ bd ready --claim ─▶ pick & claim a task
                 └─ /implement ─▶ code + tests, Google style      (implementer)
                      └─ /review-ac ─▶ gate vs acceptance criteria (reviewer)
                           └─ commit (Conventional Commits + bead id) ─▶ PR ─▶ release
                                └─ aiflow close-sync ─▶ push + Dolt-sync issues

One feature end to end — task, pre-analysis, PO question with recorded decision, versioned + secured API, tests + .http file, review gate, close:

A task is DONE only when: acceptance criteria met • tests pass • style/lint clean • review gate passed • bead closed • sync gate honoured.

Branching models

Configured at aiflow init / change-settings (only when VCS = git). aiflow writes .aiflow/branching.json + a readable docs/branching.md, creates permanent branches, seeds VERSION, and installs enforcement.

• Model — simple (main + develop) · gitflow (feature/* from develop, hotfix/* from main) · none.
• Strict rules — enforce branch sources/targets and naming.
• PR-only — no direct push to main/develop; merge only via a validated PR.
• Auto-release — merging develop → main cuts a release.
• Version strategy — SemVer or CalVer; optional release tags.
• chore/* — chore branches independent of feature/hotfix rules.

Enforcement: the pre-push hook blocks direct pushes to protected branches; aiflow protect applies real server-side branch protection on GitHub; aiflow release [--push] bumps the version, tags, and bumps develop.

Autonomous work: the Ralph loop

For larger tasks, hand off to the Ralph loop — the agent iterates until COMPLETE or BLOCKED.

• Interactive: /ralph-loop inside Claude Code.
• Headless: aiflow ralph "implement bd-12" — each iteration writes result.json; tuned via .env (RALPH_MAX_ITERATIONS, RALPH_TIMEOUT_SECONDS, RALPH_PERMISSION_MODE).
• In CI: the same loop runs via .github/workflows/agent.yml on manual dispatch, the agent issue label, or nightly.
• Containerised: docker/run.sh runs it in a container using Podman or Docker (auto-detected; override with AIFLOW_CONTAINER=podman|docker).

CI/CD for the aiflow repo

• .github/workflows/ci.yml — validates the toolchain on push/PR: bash -n on all scripts, shellcheck (advisory), JSON validation of templates, PowerShell parse, and a dry-run build of the per-OS archives (uploaded as an artifact).
• .github/workflows/release.yml — on every push to main, if VERSION has no matching tag it builds per-OS archives (linux.tar.gz, macos.tar.gz, windows.zip + SHA256SUMS), tags v<VERSION>, and publishes a GitHub Release. Bump VERSION, push → a release is cut.
• .github/workflows/pages.yml — builds and deploys this documentation site.

Projects generated by aiflow also get their own ci.yml (detects Node/Python/Go/Dart → format + tests) and agent.yml (Ralph loop in CI; auth from ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN repo secrets).

Building locally the same way CI does

ver=$(cat VERSION); stage="aiflow-$ver"
mkdir -p "dist/$stage" && cp -r bin lib templates install.sh install.ps1 README*.md LICENSE VERSION "dist/$stage/"
( cd dist && tar -czf "aiflow-$ver-linux.tar.gz" "$stage" )