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 --> [*]

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 no-AI 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, scans overlapping chunks, and blocks high-risk prompt-injection content with gvi:blocked. The runner keeps the same gate before each LLM call, including role-group 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 pre-cutoff prompt-injection input for one rerun. It still scans all context created or edited after the label. 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

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

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]

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.

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

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

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.