Skip to content

workflow-guide.md

Latest commit

 

History

History
95 lines (68 loc) · 3.27 KB

workflow-guide.md

File metadata and controls

95 lines (68 loc) · 3.27 KB

Workflow Guide (v10.2)

This project is dev-first and skills-gated:

  • GitHub can require a PR, while ICA enforces “review required” via an ICA-REVIEW-RECEIPT.
  • The agent performs merges itself (gh pr merge), never GitHub auto-merge (--auto).

Branch Workflow (Dev-First)

feature/*  -> PR -> dev  -> (release PR) -> main
  • dev is the integration branch (all feature work merges here first).
  • main is stable releases only (merge dev to main only when releasing).

Review Required (Skills-Level Gate)

Every merge must have a fresh PR receipt that matches the current head SHA:

  • Comment marker: ICA-REVIEW-RECEIPT
  • Stage: Reviewer-Stage: 3 (temp checkout)
  • Must include:
    • Head-SHA: <sha> matching the PR’s current headRefOid
    • Findings: 0 and NO FINDINGS
    • Result: PASS

If any new commits are pushed after the receipt, Stage 3 must be re-run and a new receipt posted.

Merge Approval

Default: the agent waits for explicit user approval before merging.

Optional: standing approval ("auto-merge") once gates pass:

  • Tier default (recommended): set auto_merge=true in ica.workflow.json for the task tiers you want.
  • Per-AgentTask override: set workflow.auto_merge: true inside the AgentTask YAML.

Optional GitHub-Style Approvals

By default, this repo uses self-review-and-merge:

  • PR required (branch protection), GitHub required approvals may remain at 0.
  • ICA Stage 3 receipt is the required review gate.

If you want to also require a GitHub-native approval gate, set:

  • Tier default: require_github_approval=true in ica.workflow.json
  • Per-AgentTask override: workflow.require_github_approval: true

Note: GitHub forbids approving your own PR. If you require GitHub approvals for self-authored PRs, you need a second GitHub identity/bot.

Release Workflow

Release is a separate workflow (explicitly requested):

  1. Stabilize dev (tests pass, no blocking findings).
  2. Create a release PR: dev -> main.
  3. Bump version + update CHANGELOG.md.
  4. Stage 3 review on the release PR and post a PASS receipt.
  5. Merge release PR to main (explicit approval).
  6. Tag and publish release:
    • git tag -a vX.Y.Z -m "Release vX.Y.Z"
    • git push origin vX.Y.Z
    • GitHub Actions release-sign workflow builds deterministic artifacts, verifies reproducibility, signs (keyless), attests provenance, and publishes the GitHub release.
  7. Sync main back into dev (release PR is often squashed on main).

Configuration

Workflow settings live in ica.workflow.json with the hierarchy documented in docs/configuration-guide.md.

Common examples:

{
  "medium": { "auto_merge": true },
  "large":  { "auto_merge": true },
  "mega":   { "auto_merge": true }
}
{
  "medium": { "require_github_approval": true },
  "large":  { "require_github_approval": true },
  "mega":   { "require_github_approval": true }
}

Skills Used

  • process: end-to-end dev workflow (test/review/suggest loops, PR phase, release phase)
  • reviewer: Stage 1/2/3 review with auto-fix and receipt posting (Stage 3)
  • commit-pr: commit + PR conventions and merge gates
  • pr-automerge: closed-loop review/fix/re-review/receipt/merge (for PRs to dev)
  • release: version bump, changelog, tag, GitHub release