AIGate Operations Guide

Overview

What Has Been Built

AIGate is a CLI that checks local changes, secret risk, project foundation score, pull request readiness, and release readiness.

The package is public on npm as aigate-cli and can be released automatically from GitHub tags through npm Trusted Publishing.

It can also generate Codex, Gemini, and Claude Code integration files so AI assistants follow the same repository rules.

npm

Install And Quick Start

You can run it immediately through npx without installing it globally.

npm install -g aigate-cli
aigate --version
aigate check

npx aigate-cli check

Process

End-To-End Operating Process

AIGate keeps the same quality gate from local development through PR review, CI, release, and npm publishing.

Process

Situational Usage Examples

AIGate is not one command for every moment. It gives you short routines for different repository states and risk levels.

Situation

Adopting AIGate in a repository

Process

Choose the default setup path, then add missing docs, AI instructions, and hooks step by step.

Example commands

aigate start --route default --ask-steps
aigate doctor
aigate install-hook --pre-push

Situation

After an AI agent changes many files

Process

Inspect changed files and secret risk first, then turn failing tests into an AI remediation prompt.

Example commands

aigate check
aigate test
aigate aitest

Situation

Right before opening a PR

Process

Pass the local gate, push through the guarded wrapper, and generate reviewer context.

Example commands

aigate git-ready
aigate push -u origin feature/my-work
aigate pr-check

Situation

Private GitLab monorepo

Process

Pin the profile, run workspace tests with turbo-aware fallback, and keep GitHub/npm package gates out of app scores.

Example commands

aigate setup --hosting gitlab --ci-provider gitlab --project-type app --package-manager pnpm
aigate test
aigate evaluate-project

Situation

Preparing an open source launch

Process

Create public contribution files and check repository foundation score.

Example commands

aigate start --route oss --owner @team
aigate evaluate-project --deep --report
aigate github setup --dry-run

Situation

Before and after a release

Process

Check tag/npm readiness, run CI, and record the health trend after publishing.

Example commands

aigate release-check --npm
npm run ci
aigate trends record

Situation

Clearing or removing local AIGate state

Process

Preview deletion targets first, then apply only when the target list is correct.

Example commands

aigate clean
aigate clean --force
aigate uninstall --force

Release

Release Automation Chart

After the first public release, version bumps and tag pushes are the main release triggers.

Commands

Command Map

Setup

startstart --route defaultstart --route ossinitresetsetupsettingsintegrate

First run

doctordemoinstall-hook

Guard gates

checktestaitestgit-readypushpr

Maintenance

cleanuninstalldelete

Reports

ai reportpr-checkgithub commentgithub checkgithub setuptrendsreportevaluate-projectverify-enforcementcompliance-reportdashboardaudit-report

Release

release-checkrelease-check --npmbranch-strategybranch-strategy --comparenotify

Commands

Commands And When To Use Them

Command	Purpose	When to use it
`npm install -g aigate-cli`	Install the CLI globally.	First-time developer setup
`npx aigate-cli check`	Check the repository without installing.	Quick trial or pre-CI check
`aigate start`	Run a guided project setup route with arrow keys or --route.	When adopting AIGate in a project
`aigate start --route default --ask-steps`	Ask yes/no for each recommended setup step before running it.	When you want guided control over the first setup
`aigate start --route default --steps init,repo-files`	Run only selected setup step IDs and skip the rest.	Repeatable onboarding or documented setup
`aigate start --route oss --owner @team`	Create README, contribution docs, issue templates, PR template, and CODEOWNERS.	Opening the public contribution path
`aigate start --route ai --provider all`	Create AIGate config plus Codex/Gemini/Claude instruction files.	When aligning AI assistants at once
`aigate init`	Create starter configuration and report folders.	When adopting AIGate in a new project
`aigate reset`	Rewrite AIGate config, settings, and report placeholders.	Resetting AIGate to a clean local setup
`aigate clean --force`	Delete generated AIGate reports and local generated state.	Clearing reports and generated state
`aigate uninstall --force`	Remove AIGate config, the .aigate directory, and an AIGate-owned hook.	Removing AIGate from a project
`aigate setup --language <en\|ko\|ja\|zh>`	Save the CLI output language.	When aligning team language
`aigate setup --hosting gitlab --ci-provider gitlab`	Save a GitLab project profile.	Internal GitLab apps where GitHub assumptions do not apply
`aigate settings`	Show current AIGate settings.	Configuration review
`aigate doctor`	Diagnose first-run environment, Git hook, and project foundations.	First run or repository health check
`aigate demo`	Show the AIGate workflow without changing files.	Trying the CLI or explaining it to a team
`aigate install-hook --pre-push`	Install a pre-push hook that runs git-ready before git push.	Preventing risky pushes locally
`aigate check`	Summarize changed files, active secret findings, and sensitive file removals.	Light pre-commit check
`aigate test`	Run Git readiness and detected root script, turbo task, pnpm workspace, or workspace package tests. If no turbo runner is available, fall back to workspace scripts.	Before committing with real test coverage
`aigate ai report`	Summarize current problems, strengths, direction, and an AI handoff prompt.	Before asking AI to improve the project
`aigate ai report --apply --provider codex`	Hand the AI project brief to an AI CLI, stream agent output, and capture stdout/stderr in the report.	When you explicitly allow AI automation
`aigate aitest`	Write a focused AI remediation prompt from failing tests.	When handing a failure to an AI agent
`aigate aitest --apply --provider codex`	Invoke an AI CLI and show the execution log, exit code, stdout, and stderr.	When you explicitly allow AI remediation
`aigate git-ready`	Run tests, secret scan, and project score gates.	Required before commit or push
`aigate push -u origin <branch>`	Run the gate, then forward to git push.	When publishing a branch
`aigate pr-check`	Generate a PR readiness report.	Before writing the PR description
`aigate pr --title "..."`	Create a PR through GitHub CLI.	After pushing a branch
`aigate github comment --pr <number>`	Post an AIGate summary comment to a pull request.	Leaving gate results for reviewers
`aigate github check --format json`	Generate a GitHub Checks/Actions summary payload.	Showing AIGate status in CI
`aigate github setup --owner @team`	Set up PR templates and CODEOWNERS.	Opening the public contribution path
`aigate trends record`	Record a project health snapshot.	Tracking state before and after releases
`aigate trends show`	Summarize recorded health trends.	Team review or weekly checks
`aigate report --format markdown`	Print a local workflow report.	Status sharing
`aigate report --format sarif`	Print secret findings as SARIF.	Security tool integration
`aigate evaluate-project`	Score repository foundations.	Open source readiness review
`aigate evaluate-project --deep --report`	Render a detailed report with Git signals.	Release or quarterly review
`aigate verify-enforcement --apply`	Verify required server-side AIGate checks through GitHub/GitLab APIs and record verified evidence.	When confirming CI is truly required before merge
`aigate compliance-report`	Generate a compliance control report.	Audit and operations readiness sharing
`aigate dashboard`	Write a local HTML health dashboard.	Starting self-hosted reporting
`aigate branch-strategy`	Recommend a branch strategy for team and release cadence.	Branch policy design
`aigate branch-strategy --compare`	Compare branch strategy proposals by score, strengths, risks, and migration steps.	Choosing the right branch model for a team
`aigate branch-strategy --apply`	Generate branch policy, release, hotfix, PR, CODEOWNERS, and policy pack drafts.	Starting policy files
`aigate integrate all`	Generate Codex, Gemini, and Claude Code integration files.	Keeping AI assistants aligned
`aigate release-check`	Check package, workflow, and tag readiness.	Before creating a release tag
`aigate release-check --npm`	Detect the repository profile, check npm registry/GitHub/GitLab/package-manager state, and exclude npm/package-version gates that do not apply to apps.	Before and after automated publishing
`aigate audit-report`	Summarize governance and policy posture.	Operational audit and public readiness
`aigate notify send --channel terminal`	Print a local notification event.	Checking gate-block events
`aigate git-ready --notify-channel slack`	Send a Slack webhook notification when a BLOCK occurs.	When secrets or risky changes block the gate
`aigate notify test --channel slack`	Test Slack, Discord, Teams, email, Linear, and Jira payloads.	Validating team channel integrations

Git

Branch And Delivery Flow

main is the protected stable branch. Work happens on codex/*, feature/*, fix/*, docs/*, and chore/* branches, then lands through PRs. release/* and hotfix/* are reserved for release stabilization and urgent fixes.

npm install -g aigate-cli
aigate setup --language en
aigate ai report
aigate start --route default --ask-steps
aigate start --route oss --dry-run
aigate reset --dry-run
aigate clean
aigate start --route ai --provider all
git switch -c feature/my-change
aigate doctor
aigate install-hook --pre-push
aigate test
aigate aitest
aigate git-ready
git add <files>
git commit -m "feat: short summary"
aigate push -u origin feature/my-change
aigate pr-check --output .aigate/reports/pr.md
aigate pr --title "feat: short summary"
aigate github comment --pr <number>
aigate github check --output .aigate/reports/github-check.md
aigate trends record
aigate branch-strategy --compare
aigate github setup --owner @your-org/team --dry-run
aigate release-check --npm

Features

Implemented Features

Public npm package aigate-cli and npx execution

Git change and untracked-file readiness checks

Guided start routes through aigate start

Stepwise default setup through aigate start --route default

Reset and deletion commands through aigate reset, clean, and uninstall

Open-source starter files through aigate start --route oss

Turbo-aware root and workspace test automation through aigate test

pnpm-workspace.yaml, package.json workspaces, apps/*, and packages/* test detection with fallback

AI project health briefs through aigate ai report

AI remediation prompt, live agent logs, and optional agent execution through aigate aitest

First-run UX through doctor, demo, and install-hook

generatedBy version drift warnings through doctor

Pre-push Git hook installation

Advisory, partial, and verified server-enforced AIGate diagnostics through doctor and evaluate-project

Live GitHub/GitLab server enforcement verification and evidence recording through verify-enforcement

A-grade score cap in evaluate-project when an AIGate CI gate exists without verified server enforcement

Secret pattern detection and SARIF output

git-ready, guarded push, and guarded PR creation

GitHub PR comments and GitHub Checks summary payloads

PR template and CODEOWNERS guided setup

Reusable public GitHub Action

Project health trend history

Automatic and pinned profile support for private apps, GitLab, and pnpm

GitHub/GitLab profile consistency across doctor, AI instructions, and branch policy packs

Markdown, HTML, JSON, and SARIF reports

Compliance reports and a local HTML health dashboard

Project scoring and deep Git signal evaluation

Branch strategy recommendations, proposal comparison, and policy pack generation

Codex/Gemini/Claude Code integration file generation

Korean/English/Japanese/Chinese CLI settings

release-check and app-aware release-check --npm

Automated npm releases through Trusted Publishing

GitHub CI, OpenSSF Scorecard, and GitHub Releases

Terminal, Slack BLOCK, Discord, Teams, email, Linear, and Jira notifications

Published GHCR Docker image and Homebrew tap

Features

Future Features

Product-grade Slack BLOCK notification UX

Central notification policy hardening

Deeper Linear/Jira workflow integrations

Standalone binary distribution

Organization dashboards

SSO/SAML and enterprise governance