providers

type AgentSkillsInitializer ¶ added in v0.0.9

type AgentSkillsInitializer struct {
	// contains filtered or unexported fields
}

AgentSkillsInitializer copies an embedded skill directory to a target path. This initializer handles copying entire skill directories from embedded templates to the project filesystem, preserving directory structure and file permissions (e.g., executable scripts).

Skills follow the AgentSkills specification (https://agentskills.io) and must contain at minimum a SKILL.md file.

func NewAgentSkillsInitializer(
	skillName, targetDir string,
	tm TemplateManager,
) *AgentSkillsInitializer

init := NewAgentSkillsInitializer(
	"spectr-accept-wo-spectr-bin",
	".claude/skills/spectr-accept-wo-spectr-bin",
	tm,
)

func (a *AgentSkillsInitializer) Init(
	ctx context.Context,
	projectFs, homeFs afero.Fs,
	cfg *Config,
	tm TemplateManager,
) (InitResult, error)

func (a *AgentSkillsInitializer) IsSetup(
	projectFs, _ afero.Fs,
	_ *Config,
) bool

type AiderProvider ¶

type AiderProvider struct{}

AiderProvider implements the Provider interface for Aider. Aider uses .aider/commands/spectr/ for slash commands (no config file).

func (*AiderProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type AntigravityProvider ¶

type AntigravityProvider struct{}

AntigravityProvider implements the Provider interface for Antigravity. Antigravity uses AGENTS.md and .agent/workflows/ for prefixed slash commands (spectr-proposal.md, spectr-apply.md).

func (*AntigravityProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type ClaudeProvider ¶

type ClaudeProvider struct{}

ClaudeProvider implements the Provider interface for Claude Code. Claude Code uses CLAUDE.md and .claude/commands/spectr/ for slash commands.

func (*ClaudeProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type ClineProvider ¶

type ClineProvider struct{}

ClineProvider implements the Provider interface for Cline. Cline uses CLINE.md and .clinerules/commands/spectr/ for slash commands.

func (*ClineProvider) Initializers(_ context.Context, tm TemplateManager) []Initializer

type CodexProvider ¶

type CodexProvider struct{}

CodexProvider implements the Provider interface for Codex CLI. Codex uses AGENTS.md and global ~/.codex/prompts/ for prefixed slash commands (spectr-proposal.md, spectr-apply.md).

func (*CodexProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type Config ¶ added in v0.0.9

type Config struct {
	// SpectrDir is the base directory for spectr files,
	// relative to the project root.
	// Example: "spectr"
	// Must not be empty, absolute, or contain path traversal.
	SpectrDir string
}

Config holds configuration for provider initialization. All paths are derived from SpectrDir to ensure consistency.

func (c *Config) AgentsFile() string

func (c *Config) ChangesDir() string

func (c *Config) ProjectFile() string

func (c *Config) SpecsDir() string

func (c *Config) Validate() error

type ConfigFileInitializer ¶ added in v0.0.9

type ConfigFileInitializer struct {
	// contains filtered or unexported fields
}

ConfigFileInitializer creates or updates instruction files with marker-based content. //nolint:lll Uses <!-- spectr:start --> and <!-- spectr:end --> markers (case-insensitive read, lowercase write). //nolint:lll

func (c *ConfigFileInitializer) Init(
	ctx context.Context,
	projectFs, homeFs afero.Fs,
	cfg *Config,
	tm TemplateManager,
) (InitResult, error)

func (c *ConfigFileInitializer) IsSetup(projectFs, _ afero.Fs, _ *Config) bool

type ContinueProvider ¶

type ContinueProvider struct{}

ContinueProvider implements the Provider interface for Continue. Continue uses .continue/commands/spectr/ for slash commands (no config file).

func (*ContinueProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type CostrictProvider ¶

type CostrictProvider struct{}

CostrictProvider implements the Provider interface for CoStrict. CoStrict uses COSTRICT.md and .costrict/commands/spectr/ for slash commands.

func (*CostrictProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type CrushProvider ¶ added in v0.0.8

type CrushProvider struct{}

CrushProvider implements the Provider interface for Crush. Crush uses CRUSH.md and .crush/commands/spectr/ for slash commands.

func (*CrushProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type CursorProvider ¶

type CursorProvider struct{}

CursorProvider implements the Provider interface for Cursor. Cursor uses .cursorrules/commands/spectr/ for slash commands (no config file).

func (*CursorProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type DirectoryInitializer ¶ added in v0.0.9

type DirectoryInitializer struct {
	// contains filtered or unexported fields
}

DirectoryInitializer creates directories in the project filesystem. Multiple paths can be created in a single initializer. Uses MkdirAll semantics - creates parent directories if needed, succeeds silently if directory exists. //nolint:lll

func (d *DirectoryInitializer) Init(
	ctx context.Context,
	projectFs, homeFs afero.Fs,
	cfg *Config,
	tm TemplateManager,
) (InitResult, error)

func (d *DirectoryInitializer) IsSetup(
	projectFs, _ afero.Fs,
	_ *Config,
) bool

type ExecutionResult ¶ added in v0.0.9

type ExecutionResult struct {
	// CreatedFiles is the list of all files created
	// across all initializers.
	CreatedFiles []string

	// UpdatedFiles is the list of all files updated
	// across all initializers.
	UpdatedFiles []string
}

ExecutionResult aggregates results from all initializers. This is the final result returned after running all initializers.

Note: Error is returned separately from the executor function, not stored in this struct. This allows partial results to be returned even when an error occurs (fail-fast behavior).

type GeminiProvider ¶

type GeminiProvider struct{}

GeminiProvider implements the Provider interface for Gemini CLI. Gemini uses .gemini/commands/spectr/ for TOML-based slash commands (no instruction file). //nolint:lll

func (*GeminiProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type HomeDirectoryInitializer ¶ added in v0.0.9

type HomeDirectoryInitializer struct {
	// contains filtered or unexported fields
}

HomeDirectoryInitializer creates directories in the home filesystem. Multiple paths can be created in a single initializer. Uses MkdirAll semantics - creates parent directories if needed, succeeds silently if directory exists. //nolint:lll

func (h *HomeDirectoryInitializer) Init(
	ctx context.Context,
	projectFs, homeFs afero.Fs,
	cfg *Config,
	tm TemplateManager,
) (InitResult, error)

func (h *HomeDirectoryInitializer) IsSetup(
	_, homeFs afero.Fs,
	_ *Config,
) bool

type HomePrefixedSlashCommandsInitializer ¶ added in v0.0.9

type HomePrefixedSlashCommandsInitializer struct {
	// contains filtered or unexported fields
}

HomePrefixedSlashCommandsInitializer creates Markdown slash command files with custom prefix in home filesystem. Used by providers like Codex that need custom file naming in home directory. Output: {dir}/{prefix}{command}.md (e.g., ~/.codex/prompts/spectr-proposal.md)

func (h *HomePrefixedSlashCommandsInitializer) Init(
	_ context.Context,
	_, homeFs afero.Fs,
	cfg *Config,
	_ TemplateManager,
) (InitResult, error)

func (h *HomePrefixedSlashCommandsInitializer) IsSetup(
	_, homeFs afero.Fs,
	_ *Config,
) bool

type HomeSlashCommandsInitializer ¶ added in v0.0.9

type HomeSlashCommandsInitializer struct {
	// contains filtered or unexported fields
}

HomeSlashCommandsInitializer creates Markdown slash command files in the home filesystem. Uses early binding - templates are resolved at construction time. Always overwrites existing files (idempotent behavior).

func (h *HomeSlashCommandsInitializer) Init(
	_ context.Context,
	_, homeFs afero.Fs,
	cfg *Config,
	_ TemplateManager,
) (InitResult, error)

func (h *HomeSlashCommandsInitializer) IsSetup(_, homeFs afero.Fs, _ *Config) bool

type InitResult ¶ added in v0.0.9

type InitResult struct {
	// CreatedFiles is the list of files that were newly created.
	// Paths should be relative to the filesystem root (projectFs or homeFs).
	CreatedFiles []string

	// UpdatedFiles is the list of files that already existed and were modified.
	// Paths should be relative to the filesystem root (projectFs or homeFs).
	UpdatedFiles []string
}

InitResult contains the files created or modified by an initializer. This provides explicit change tracking for each initialization step.

type Initializer ¶ added in v0.0.9

type Initializer interface {
	// Init creates or updates files for this initializer.
	// Returns InitResult with created/updated file paths and error if initialization fails.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout
	//   - projectFs: Filesystem rooted at project directory (for .claude/, CLAUDE.md, etc.)
	//   - homeFs: Filesystem rooted at user home directory (for ~/.codex/, etc.)
	//   - cfg: Configuration with SpectrDir and derived paths
	//   - tm: TemplateManager for rendering templates
	//
	// The initializer decides which filesystem to use based on its type
	// (e.g., DirectoryInitializer uses projectFs, HomeDirectoryInitializer uses homeFs).
	Init(
		ctx context.Context,
		projectFs, homeFs afero.Fs,
		cfg *Config,
		tm TemplateManager,
	) (InitResult, error)

	// IsSetup returns true if this initializer's artifacts already exist.
	//
	// Parameters:
	//   - projectFs: Filesystem rooted at project directory
	//   - homeFs: Filesystem rooted at user home directory
	//   - cfg: Configuration with SpectrDir and derived paths
	//
	// The initializer checks the appropriate filesystem based on its type.
	//
	// PURPOSE: Used by the setup wizard to show which providers are already configured.
	// NOT used to skip initializers during execution - Init() always runs (idempotent).
	IsSetup(projectFs, homeFs afero.Fs, cfg *Config) bool
}

Initializer represents a unit of initialization work that creates or updates files. Each initializer is responsible for a specific aspect of provider configuration (e.g., creating directories, updating config files, creating slash commands).

Initializers must be idempotent - they can be run multiple times safely.

func NewConfigFileInitializer(path string, template domain.TemplateRef) Initializer

func NewDirectoryInitializer(paths ...string) Initializer

func NewHomeDirectoryInitializer(paths ...string) Initializer

func NewHomePrefixedSlashCommandsInitializer(
	dir, prefix string,
	commands map[domain.SlashCommand]domain.TemplateRef,
) Initializer

func NewHomeSlashCommandsInitializer(
	dir string,
	commands map[domain.SlashCommand]domain.TemplateRef,
) Initializer

func NewPrefixedSlashCommandsInitializer(
	dir, prefix string,
	commands map[domain.SlashCommand]domain.TemplateRef,
) Initializer

func NewSlashCommandsInitializer(
	dir string,
	commands map[domain.SlashCommand]domain.TemplateRef,
) Initializer

Example: NewSlashCommandsInitializer(".claude/commands/spectr", map[domain.SlashCommand]domain.TemplateRef{ //nolint:lll
    domain.SlashProposal: tm.SlashCommand(domain.SlashProposal),
    domain.SlashApply: tm.SlashCommand(domain.SlashApply),
})

func NewTOMLSlashCommandsInitializer(
	dir string,
	commands map[domain.SlashCommand]domain.TemplateRef,
) Initializer

Example: NewTOMLSlashCommandsInitializer(".gemini/commands/spectr", map[domain.SlashCommand]domain.TemplateRef{
    domain.SlashProposal: tm.TOMLSlashCommand(domain.SlashProposal),
    domain.SlashApply: tm.TOMLSlashCommand(domain.SlashApply),
})

type KilocodeProvider ¶

type KilocodeProvider struct{}

KilocodeProvider implements the Provider interface for Kilocode. Kilocode uses .kilocode/commands/spectr/ for slash commands (no config file).

func (*KilocodeProvider) Initializers(_ context.Context, tm TemplateManager) []Initializer

type OpencodeProvider ¶ added in v0.0.8

type OpencodeProvider struct{}

OpencodeProvider implements the Provider interface for OpenCode. OpenCode uses .opencode/commands/spectr/ for slash commands (no config file).

func (*OpencodeProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type PrefixedSlashCommandsInitializer ¶ added in v0.0.9

type PrefixedSlashCommandsInitializer struct {
	// contains filtered or unexported fields
}

PrefixedSlashCommandsInitializer creates Markdown slash command files with custom prefix in project filesystem. Used by providers like Antigravity that need custom file naming. Output: {dir}/{prefix}{command}.md (e.g., .agent/workflows/spectr-proposal.md)

func (p *PrefixedSlashCommandsInitializer) Init(
	_ context.Context,
	projectFs, _ afero.Fs,
	cfg *Config,
	_ TemplateManager,
) (InitResult, error)

func (p *PrefixedSlashCommandsInitializer) IsSetup(projectFs, _ afero.Fs, _ *Config) bool

type Provider ¶

type Provider interface {
	// Initializers returns the list of initializers for this provider.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout
	//   - tm: TemplateManager for type-safe template access
	//
	// The TemplateManager provides type-safe accessors like:
	//   - tm.InstructionPointer() - for CLAUDE.md, CLINE.md, etc.
	//   - tm.Agents() - for AGENTS.md
	//   - tm.SlashCommand(domain.SlashProposal) - for Markdown
	//   - tm.TOMLSlashCommand(domain.SlashProposal) - for TOML (Gemini)
	//
	// Example:
	//	func (p *ClaudeProvider) Initializers(
	//		ctx context.Context,
	//		tm TemplateManager,
	//	) []Initializer {
	//		return []Initializer{
	//			NewDirectoryInitializer(".claude/commands/spectr"),
	//			NewConfigFileInitializer(
	//				"CLAUDE.md",
	//				tm.InstructionPointer(),
	//			),
	//			NewSlashCommandsInitializer(
	//				".claude/commands/spectr",
	//				map[domain.SlashCommand]domain.TemplateRef{
	//					domain.SlashProposal: tm.SlashCommand(
	//						domain.SlashProposal,
	//					),
	//					domain.SlashApply: tm.SlashCommand(
	//						domain.SlashApply,
	//					),
	//				},
	//			),
	//		}
	//	}
	Initializers(ctx context.Context, tm TemplateManager) []Initializer
}

Provider represents an AI CLI tool (Claude Code, Gemini, Cline, etc.). Each provider returns a list of initializers that configure the tool.

Provider metadata (ID, Name, Priority) is specified at registration time via the Registration struct, not as methods on this interface.

type QoderProvider ¶

type QoderProvider struct{}

QoderProvider implements the Provider interface for Qoder. Qoder uses QODER.md and .qoder/commands/spectr/ for slash commands.

func (*QoderProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type QwenProvider ¶

type QwenProvider struct{}

QwenProvider implements the Provider interface for Qwen Code. Qwen Code uses QWEN.md and .qwen/commands/spectr/ for slash commands.

func (*QwenProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer

type Registration ¶ added in v0.0.9

type Registration struct {
	// ID is the unique provider identifier (kebab-case).
	// Examples: "claude-code", "gemini", "cline"
	// Must be unique across all registered providers.
	ID string

	// Name is the human-readable provider name for display.
	// Examples: "Claude Code", "Gemini CLI", "Cline"
	// Used in UI elements like the setup wizard.
	Name string

	// Priority determines the display order (lower = higher priority).
	// Claude Code should be 1, other major tools 2-10, etc.
	// Used to sort providers in lists and determine which provider wins
	// during initializer deduplication (higher priority = kept first).
	Priority int

	// Provider is the implementation that returns initializers.
	// Must not be nil.
	Provider Provider
}

Registration contains provider metadata and implementation. This struct is used during provider registration to associate a provider implementation with its identifying information.

func Get(id string) (Registration, bool)

func RegisteredProviders() []Registration

type SlashCommandsInitializer ¶ added in v0.0.9

type SlashCommandsInitializer struct {
	// contains filtered or unexported fields
}

SlashCommandsInitializer creates Markdown slash command files in the project filesystem. //nolint:lll Uses early binding - templates are resolved at construction time. Always overwrites existing files (idempotent behavior).

func (s *SlashCommandsInitializer) Init(
	_ context.Context,
	projectFs, _ afero.Fs,
	cfg *Config,
	_ TemplateManager,
) (InitResult, error)

func (s *SlashCommandsInitializer) IsSetup(projectFs, _ afero.Fs, _ *Config) bool

type TOMLSlashCommandsInitializer ¶ added in v0.0.9

type TOMLSlashCommandsInitializer struct {
	// contains filtered or unexported fields
}

TOMLSlashCommandsInitializer creates TOML slash command files in the project filesystem. Used by Gemini provider for TOML format. Uses early binding - templates are resolved at construction time. Always overwrites existing files (idempotent behavior). //nolint:lll

func (t *TOMLSlashCommandsInitializer) Init(
	_ context.Context,
	projectFs, _ afero.Fs,
	cfg *Config,
	_ TemplateManager,
) (InitResult, error)

func (t *TOMLSlashCommandsInitializer) IsSetup(projectFs, _ afero.Fs, _ *Config) bool

type TemplateManager ¶ added in v0.0.9

type TemplateManager interface {
	// InstructionPointer returns the template for instruction pointer files
	// (CLAUDE.md, CLINE.md, etc.)
	InstructionPointer() domain.TemplateRef

	// Agents returns the template for the AGENTS.md file
	Agents() domain.TemplateRef

	// SlashCommand returns the template for a Markdown slash command
	SlashCommand(cmd domain.SlashCommand) domain.TemplateRef

	// TOMLSlashCommand returns the template for a TOML slash command
	TOMLSlashCommand(cmd domain.SlashCommand) domain.TemplateRef

	// SkillFS returns an fs.FS rooted at the skill directory for the given
	// skill name. Returns an error if the skill does not exist.
	// The filesystem contains all files under templates/skills/<skillName>/
	// with paths relative to the skill root (e.g., SKILL.md, scripts/accept.sh).
	SkillFS(skillName string) (fs.FS, error)
}

TemplateManager is defined in internal/initialize/templates.go. We define it as an interface here to avoid import cycles. The actual implementation is passed from the executor.

type WindsurfProvider ¶

type WindsurfProvider struct{}

WindsurfProvider implements the Provider interface for Windsurf. Windsurf uses .windsurf/commands/spectr/ for slash commands (no config file).

func (*WindsurfProvider) Initializers(
	_ context.Context,
	tm TemplateManager,
) []Initializer