Scaffold OpenCode agent and command files into the current directory. After running this command, you can use the /gaze command in OpenCode to generate AI-powered quality reports.
gaze init [flags]This command takes no positional arguments. It always operates on the current working directory.
| Flag | Type | Default | Description |
|---|---|---|---|
--force |
bool |
false |
Overwrite all scaffolded files — the nine .opencode/ assets even when their content is identical, and the CI workflow when run with --ci. Without this flag, .opencode/ files update automatically when their content differs; only the user-owned CI workflow needs --force to be regenerated. |
--ci |
bool |
false |
Also scaffold .github/workflows/gaze-ai-report.yml, a starter caller for gaze's reusable AI-report workflow. Requires a go.mod at the repository root; skipped with a warning otherwise. |
--gaze-version |
string |
"" |
Gaze release tag (>= v2.3.0) pinning the scaffolded CI workflow's uses: reference. Requires --ci. |
The init command creates 9 files with the following directory structure:
.opencode/
├── agents/
│ ├── gaze-reporter.md # AI agent prompt for quality reporting (tool-owned)
│ ├── gaze-test-generator.md # Test generation agent
│ └── divisor-gaze-testing.md # Test-quality reviewer persona for review councils
├── commands/
│ ├── gaze.md # /gaze command definition (tool-owned)
│ ├── gaze-fix.md # /gaze fix command definition
│ └── speckit.testreview.md # /speckit.testreview command definition
├── dcp.jsonc # DCP context-preservation configuration
└── references/
├── example-report.md # Canonical example output for the reporter
└── doc-scoring-model.md # Document-enhanced classification scoring model
All nine .opencode/ files scaffolded by init are tool-owned. The only user-owned scaffold output is the CI workflow that --ci writes (see CI Workflow Scaffolding):
- Tool-owned files (everything under
references/, plusagents/gaze-reporter.md,agents/gaze-test-generator.md,agents/divisor-gaze-testing.md,commands/gaze.md,commands/gaze-fix.md,commands/speckit.testreview.md, anddcp.jsonc): Updated automatically ongaze initif the content has changed, and reported asupdated. These files are maintained by Gaze and should not be manually edited — local customizations to any of them, includingcommands/gaze.md, are overwritten. - Escape hatch for customized commands: gaze only ever writes the nine embedded
.opencode/paths, so any other path under.opencode/is yours. To keep a customized/gazecommand, name itcommands/gaze-local.md: OpenCode maps it to/gaze-local, and gaze never writes that path, even under--force. Whencommands/gaze.mdis updated, the init summary ends with a tip naming this escape hatch.
When run in a project that already uses unbound-force tooling (a .uf/ directory exists), gaze init also registers the divisor-gaze-testing persona in the existing review configuration: it appends the reviewer entry to .uf/reviewer-capabilities.yaml and swaps the generic divisor-testing advisor for divisor-gaze-testing in the code, spec, triage, and feedback advisor lists of .uf/review-matrix.yaml (a matrix missing any of the four lists is skipped with a warning). The merge is idempotent, comment-preserving, and never creates .uf files — projects without a .uf/ directory get a notice instead.
gaze init also removes a legacy .opencode/agents/reviewer-testing.md when its content carries the gaze version marker (<!-- scaffolded by gaze ... -->) — the file was superseded by agents/divisor-gaze-testing.md. Marker-less (user-customized) copies are left untouched.
The --ci flag additionally scaffolds .github/workflows/gaze-ai-report.yml: a self-contained starter workflow for gaze's reusable AI-report workflow. Plain gaze init is unchanged — the flag is purely additive.
The generated workflow owns both halves of the pipeline:
- A
testjob that checks out the code, sets up Go, runsgo test -race -count=1 -short -coverprofile=coverage.out ./..., and uploads the profile as thecoverage-outartifact. - A
gaze-ai-reportjob that callsunbound-force/gaze/.github/workflows/reusable_gaze_ai_report.yml@<version>with the coverage artifact and theOPENCODE_CONFIG_CONTENTsecret.
Behavior details:
- Report-only by default. The threshold inputs (
max-crapload,max-gaze-crapload,min-contract-coverage) are emitted commented out; the workflow exits 0 until a human chooses values and uncomments them. Governance gates belong to the repository owner, not the scaffolder. - User-owned. The workflow is never overwritten by later
gaze init --ciruns (skip-if-present); only--forceregenerates it, so threshold edits survive re-scaffolding. - Version pinning. The
uses:reference is pinned to the gaze release tag resolved from the running binary's build-time version and validated as>= v2.3.0— the first release containing the reusable workflow. Dev builds (and any version below the floor) fail closed with an error instead of writing an unusable pin.--gaze-versionoverrides the pin with the same validation; it is rejected without--ci, since it affects only the CI scaffolding. - Go version from
go.mod. The workflow'ssetup-goversion is read from the module'sgodirective and validated before substitution — never passed through verbatim. When the directive is absent, unreadable, or malformed, the workflow falls back to the reusable workflow's default (1.25) with a warning. - Go module required at the repository root. The reusable workflow analyzes
./...from the repository root, so--cirequires ago.modthere. When it is absent, CI scaffolding is skipped with a distinct, non-fatal warning and the.opencode/scaffolding proceeds unchanged.
After a successful --ci run, the console prints a CI next steps section: the gh secret set OPENCODE_CONFIG_CONTENT one-liner (with a jq -c . minify tip — GitHub's multiline secret masking is unreliable), the second-secret pointer for masking API-key fragments echoed into logs, and a paste-able prompt for choosing initial threshold values from a baseline report.
This command does not read .gaze.yaml.
cd /path/to/your/go/project
gaze initNotice: no .uf directory found; skipping Divisor review-config registration.
Gaze never creates .uf files; unbound-force projects register the persona automatically.
Gaze OpenCode integration initialized:
created: .opencode/agents/divisor-gaze-testing.md
created: .opencode/agents/gaze-reporter.md
created: .opencode/agents/gaze-test-generator.md
created: .opencode/commands/gaze-fix.md
created: .opencode/commands/gaze.md
created: .opencode/commands/speckit.testreview.md
created: .opencode/dcp.jsonc
created: .opencode/references/doc-scoring-model.md
created: .opencode/references/example-report.md
Run /gaze for quality reports and /speckit.testreview for testability analysis.
gaze initOn subsequent runs, all nine .opencode/ files are updated when their content has changed and skipped when identical — --force is never needed to receive updates. When commands/gaze.md is updated, the summary ends with a tip naming the commands/gaze-local.md escape hatch:
Gaze OpenCode integration initialized:
skipped: .opencode/agents/divisor-gaze-testing.md (already exists)
...
updated: .opencode/commands/gaze.md (content changed)
Run /gaze for quality reports and /speckit.testreview for testability analysis.
Tip: commands/gaze.md is tool-owned; to keep a customized /gaze command, name it commands/gaze-local.md (gaze never writes that path).
The CI workflow is the one scaffold output that does not update automatically: an existing workflow is skipped on gaze init --ci runs, and --force regenerates it. In projects with a .uf/ directory, the persona registration is idempotent (already-registered files are not rewritten), and a gaze-marked legacy .opencode/agents/reviewer-testing.md orphan is removed with a removed: summary line.
gaze init --forceOverwrites all nine .opencode/ assets even when their content is identical, and regenerates an existing CI workflow when run with --ci. Non-embedded paths such as commands/gaze-local.md are never written, even under --force.
cd /path/to/your/go/project
gaze init --ciIn addition to the nine .opencode/ files, this writes .github/workflows/gaze-ai-report.yml and prints the CI next-steps guidance:
Gaze OpenCode integration initialized:
created: .opencode/agents/divisor-gaze-testing.md
...
created: .github/workflows/gaze-ai-report.yml
Run /gaze for quality reports and /speckit.testreview for testability analysis.
CI next steps for .github/workflows/gaze-ai-report.yml:
1. Store your opencode configuration as the OPENCODE_CONFIG_CONTENT secret:
gh secret set OPENCODE_CONFIG_CONTENT < opencode-config.json
...
A dev build (or any version below v2.3.0) fails closed instead of writing an unusable pin:
Error: gaze version "dev" cannot pin the CI workflow: the reusable AI-report workflow first ships in v2.3.0; install gaze from a release tag (>= v2.3.0) or pass --gaze-version
Pass --gaze-version v2.5.0 to pin an explicit release tag.
- OpenCode Integration — how to use
/gazeafter initialization - CI Integration — the reusable AI-report workflow the scaffolded caller invokes
gaze report— the CLI equivalent of the/gazeOpenCode command