Skip to content

Latest commit

 

History

History
171 lines (118 loc) · 10.3 KB

init.md

File metadata and controls

171 lines (118 loc) · 10.3 KB

gaze init

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.

Synopsis

gaze init [flags]

Arguments

This command takes no positional arguments. It always operates on the current working directory.

Flags

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.

Scaffolded Files

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

File Ownership 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/, plus agents/gaze-reporter.md, agents/gaze-test-generator.md, agents/divisor-gaze-testing.md, commands/gaze.md, commands/gaze-fix.md, commands/speckit.testreview.md, and dcp.jsonc): Updated automatically on gaze init if the content has changed, and reported as updated. These files are maintained by Gaze and should not be manually edited — local customizations to any of them, including commands/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 /gaze command, name it commands/gaze-local.md: OpenCode maps it to /gaze-local, and gaze never writes that path, even under --force. When commands/gaze.md is updated, the init summary ends with a tip naming this escape hatch.

Divisor Review-Config Registration

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.

CI Workflow Scaffolding

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 test job that checks out the code, sets up Go, runs go test -race -count=1 -short -coverprofile=coverage.out ./..., and uploads the profile as the coverage-out artifact.
  • A gaze-ai-report job that calls unbound-force/gaze/.github/workflows/reusable_gaze_ai_report.yml@<version> with the coverage artifact and the OPENCODE_CONFIG_CONTENT secret.

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 --ci runs (skip-if-present); only --force regenerates 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-version overrides 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's setup-go version is read from the module's go directive 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 --ci requires a go.mod there. 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.

Configuration Interaction

This command does not read .gaze.yaml.

Examples

Initialize OpenCode integration

cd /path/to/your/go/project
gaze init
Notice: 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.

Re-initialize (update tool-owned files)

gaze init

On 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.

Force overwrite all files

gaze init --force

Overwrites 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.

Scaffold the CI workflow

cd /path/to/your/go/project
gaze init --ci

In 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.

See Also