Workflows and Lifecycle

Workflows And Lifecycle

This page explains how GitVibe work moves through GitHub. Command and label syntax lives in Commands and Labels. Stage schemas and tools live in AI and Stage Contracts.

Lifecycle

stateDiagram-v2
  [*] --> Intake

  Intake --> BugIssue: bug report
  Intake --> FeatureDiscussion: feature discussion
  Intake --> ConvertedDiscussion: feature issue form
  ConvertedDiscussion --> FeatureDiscussion: create linked Discussion and close issue

  BugIssue --> Investigation: investigate label or command
  Investigation --> BugBlocked: needs context
  BugBlocked --> Investigation: maintainer answers and retries
  Investigation --> InvestigatedIssue: ready
  InvestigatedIssue --> HumanImplementation: human or external agent implements

  FeatureDiscussion --> Validation: validate label
  Validation --> FeatureBlocked: needs context
  FeatureBlocked --> Validation: maintainer clarifies and retries
  Validation --> ReadyToMaterialize: validated
  ReadyToMaterialize --> Materialize: approved label or materialize command
  Materialize --> ImplementationIssues: implementation issue created

  HumanImplementation --> PullRequest: human or external agent opens PR
  ImplementationIssues --> HumanImplementation
  PullRequest --> ReviewMatrix: automatic or git-vibe:review
  ReviewMatrix --> PullRequestReady: review passed
  ReviewMatrix --> HumanFixes: changes required

  HumanFixes --> PullRequest: update existing PR branch

  PullRequestReady --> HumanMerge: human review and merge
  HumanMerge --> [*]

Loading

Workflow Reference

Workflow	Triggered by	Main target	Writes code?
investigate.yml	/git-vibe investigate or git-vibe:investigate	Issue investigation	No
validate.yml	git-vibe:validate	Issue or Discussion	No
materialize.yml	git-vibe:approved or /git-vibe materialize on validated Discussion	Discussion to implementation issue drafts	No repository changes
review.yml	git-vibe:review on an existing PR, or repo-local wrapper automation	Pull request review matrix	No
automatic-pr-review.yml	Source-repository PR opened, reopened, synchronized, or marked ready	Repo-local wrapper around review.yml	No
ai-smoke.yml	Manual workflow dispatch	Runner/provider setup	No repository changes

Reusable workflows install Node 22 and pnpm 10.33.3, then build and run the source-backed composite action for each stage.

Every reusable workflow starts with a security-review job before any planner, role-group member, finalizer, or stage LLM job starts. It builds the target context, normalizes content into scan units, and asks the configured AI safety classifier to review overlapping chunks for high-risk prompt-injection content. Blocks apply gvi:blocked. The review-matrix finalizer fails the PR review check when the final result is blocked. A completed changes-required review keeps a successful workflow check while retaining its findings and gvi:blocked state. Other workflows keep blocked results as published GitVibe state without failing the workflow check. The runner keeps the same gate before each LLM call, including role-group members and synthesis, and runs a post-output gate before privileged state advancement.

If a maintainer applies git-vibe:accept-risk, only the security-review job uses that label to accept matching pre-cutoff prompt-injection input. It still scans all context created or edited after the label. For PR reviews, later pushes can reuse the same accepted-risk metadata only while the PR title/body hash still matches, and the current PR file diff is scanned when the head SHA changes. Once that job passes, review-matrix finalization should not carry the old security block message into the synthesizer or repost the same accepted prompt-injection question.

Bug Investigation

Bug reports do not start implementation automatically. Investigation happens before coding.

sequenceDiagram
  participant Maintainer
  participant Issue
  participant App as GitVibe app
  participant WF as investigate.yml

  Maintainer->>Issue: Add git-vibe:investigate or comment /git-vibe investigate
  Issue->>App: Webhook
  App->>App: Verify trusted actor
  App->>WF: Dispatch investigation
  WF->>Issue: Post findings, questions, and implementation readiness
  alt ready
    WF->>Issue: Add gvi:investigated
    Maintainer->>Issue: Implement directly or hand off to an external agent
  else blocked
    WF->>Issue: Add gvi:blocked
    Maintainer->>Issue: Answer questions and retry investigation
  end

Loading

Feature Validation And Materialization

Feature requests are intended to become Discussions before implementation.

sequenceDiagram
  participant Community
  participant Discussion
  participant Maintainer
  participant App as GitVibe app
  participant WF as GitVibe workflows
  participant Issue

  Community->>Discussion: Discuss feature request
  Maintainer->>Discussion: Add git-vibe:validate
  App->>WF: Dispatch validate.yml
  WF->>Discussion: Confirm readiness or ask for more context
  Maintainer->>Discussion: Add git-vibe:approved or comment /git-vibe materialize
  App->>WF: Dispatch materialize.yml
  WF->>Issue: Create implementation issue with backlinks

Loading

Community reaction thresholds are documented as planned config shape; automatic community dispatch is not the active app path today.

Development Pipeline

flowchart TD
  A[Ready issue or materialized implementation issue] --> B[Human or external agent implements]
  B --> C[Human or external agent opens or updates PR]
  C --> D[review.yml review matrix]
  D --> E{Review result}
  E -->|review-passed| F[PR gvi:ready-for-approval]
  E -->|changes-required| G[PR gvi:blocked]
  G --> B
  F --> H[Human PR review and merge]

Loading

GitVibe no longer commits code, pushes branches, creates pull requests, or fixes PR feedback. The review matrix is a PR-scoped gate for an existing pull request. Required fixes are posted on the PR and must be handled by a human or external implementation agent.

GitVibe reconciles its own inline review findings across review runs. Inline findings carry a hidden git-vibe:review-finding id marker. When the same issue still applies, the next review reuses that finding_id and GitVibe replies to the existing thread instead of opening a duplicate inline comment. When a completed, non-blocked review no longer reports a prior GitVibe finding, GitVibe replies that the finding is outdated and resolves the thread. Blocked review outputs do not mark prior findings outdated.

For role-group review, GitVibe plans matrix members, runs member jobs, and then uses one finalizer to synthesize a single review-matrix.v1 result. The finalizer receives configured role definitions and successful role outputs. It does not receive the standalone security-review result as review evidence.

Incremental PR Review Checkpoints

PR review scope is automatic. There is no review-mode setting or action input. The first review with no usable GitVibe checkpoint reviews the full pull request. Each later review starts at the target SHA recorded in the newest completed, published GitVibe review and ends at the target SHA frozen for the new run.

flowchart LR
  A[Published review at SHA A] --> B[Run for SHA B starts]
  B -->|canceled before publishing| C[New commit SHA C]
  C --> D[New run reviews A through C]
  B -->|completed result was published| E[SHA B becomes checkpoint]
  E --> F[New run reviews B through C]

Loading

Canceled, failed, blocked, and partial runs do not advance the checkpoint. A completed result may advance it whether the outcome is review-passed or changes-required, because the reviewed range and findings were durably posted. If the prior SHA is no longer an ancestor after a history rewrite, the base changed, or GitHub cannot return a complete comparison, GitVibe performs a full safe re-baseline. That run becomes the next checkpoint when it completes.

The security-review job freezes the base, checkpoint, target, file snapshot, and input-safety digest before matrix members start. Members reconstruct that same range and inspect a separate checkout whose HEAD must equal the frozen target. A result is rejected before GitHub writes if the PR head has moved.

Incremental review does not treat an omitted prior finding as fixed. Open GitVibe findings remain obligations until the output reuses their finding_id or lists the id in resolved_finding_ids with current-target evidence. GitVibe carries any other unresolved finding forward and leaves its thread open. A full review may retire an omitted prior finding because it covers the complete PR. GitVibe publishes the completed review marker before replying to or resolving prior threads, so cancellation cannot change thread state without first leaving a durable checkpoint.

PR Review Feedback

flowchart TD
  A[GitVibe review finds required fixes] --> B[PR gvi:blocked]
  B --> C[Human or external agent updates PR branch]
  C --> D[git-vibe:review label or automatic PR review rerun]
  D --> E[review.yml]
  E --> F{Review result}
  F -->|review-passed| G[gvi:ready-for-approval]
  F -->|changes-required| B

Loading

Trusted approved review submissions can mark GitVibe-traced PRs approved. changes_requested submissions are ignored and do not dispatch a feedback workflow.

Traceability

Generated artifacts link to each other through GitHub-native references and hidden markers:

flowchart LR
  Discussion -->|materialize| ImplementationIssue
  ImplementationIssue -->|human or external agent| PR
  PR -->|review| ReviewMatrix
  ReviewMatrix -->|changes required| HumanFixes
  HumanFixes -->|push fixes| PR

Loading

Result comments include workflow links when available. Runner stages delete stale transient queued/running status comments for the same artifact while keeping durable result and traceability comments.