autoinit

Documentation

Overview

Package autoinit performs a one-time, automatic codebase-analysis pass the first time hawk runs in a project that has no context files (AGENTS.md / HAWK.md / CLAUDE.md). It mirrors the behaviour of the `init-deep` skill but is gated so it runs at most once per project and can be disabled entirely.

The package is intentionally additive and self-contained: it only inspects the filesystem to decide whether to run, writes a marker file once a run has been attempted, and delegates the actual analysis to a caller-supplied runner. Callers (the cmd layer) wire the runner to whatever drives the init analysis (the init-deep skill / `hawk init`). When no runner is wired, MaybeRun is a no-op beyond gating, so importing the package never changes behaviour on its own.

Index

• func Disabled() bool
• func HasContext(root string) bool
• func HasRun(root string) bool
• func MarkerPath(root string) string
• type Decision
  • func MaybeRun(ctx context.Context, opts Options) (Decision, error)
• type Options
• type Runner

Functions

func Disabled

func Disabled() bool

Disabled reports whether auto-init is disabled via the environment.

func HasContext

func HasContext(root string) bool

HasContext reports whether root already contains a project context file.

func HasRun

func HasRun(root string) bool

HasRun reports whether auto-init has already been attempted for root.

func MarkerPath

func MarkerPath(root string) string

MarkerPath returns the path to the auto-init marker file for root.

Types

type Decision

type Decision struct {
	// Ran is true when the runner was invoked.
	Ran bool
	// Skipped is a short reason when the runner was not invoked.
	Skipped string
}

Decision reports what MaybeRun did, for logging and tests.

func MaybeRun

func MaybeRun(ctx context.Context, opts Options) (Decision, error)

MaybeRun runs the auto-init analysis at most once for opts.Root, subject to the gating rules:

1. Disabled via HAWK_DISABLE_AUTO_INIT -> skip.
2. Marker file already present -> skip.
3. Project already has a context file -> mark + skip (unless Force).
4. Otherwise -> run, then mark.

The marker is written whenever a run is attempted (even on runner error) so a failing analysis is not retried on every invocation. MaybeRun never returns an error for gating decisions; it only propagates a runner error.

type Options

type Options struct {
	// Root is the project directory to analyze. Required.
	Root string
	// Run performs the analysis. When nil, MaybeRun gates and writes the
	// marker (if it would have run) but performs no analysis.
	Run Runner
	// Force ignores the "already has context" check but still respects the
	// marker file and the disable env var. Useful for an explicit re-init.
	Force bool
	// contains filtered or unexported fields
}

Options controls a MaybeRun invocation.

type Runner

type Runner func(ctx context.Context, root string) error

Runner performs the actual codebase analysis for a project rooted at root. It is supplied by the caller so this package carries no dependency on the engine, skills, or cmd layers.