sync

package
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 17, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package sync deploys skills and subagent definitions to runtime directories.

It reads canonical agent Markdown files and skill directories from configured source paths, generates runtime-specific variants (Claude Code, OpenCode, Codex), and writes or symlinks them to the appropriate destination directories. A clean operation removes stale managed files that no longer exist in source.

Plane: shared

Index

Constants

View Source 
const ManagedMarkerField = "managed_by: ttal-sync"

ManagedMarkerField is a YAML frontmatter field embedded in deployed files so CleanAgents and CleanCommands can identify ttal-managed files and avoid deleting user-created ones.

Variables

This section is empty.

Functions

func CleanAgents 

func CleanAgents(subagentsPaths []string, dryRun bool) ([]string, error)

CleanAgents removes ttal-managed agent files that no longer exist in source paths. Only removes files containing the ManagedMarkerField to avoid deleting user-created agents. Also cleans stale Codex agent .toml files and config.toml entries.

func CleanCodexAgents 

func CleanCodexAgents(validNames map[string]bool, dryRun bool) ([]string, error)

CleanCodexAgents removes stale ttal-managed Codex agent files and config.toml entries.

func CleanCommands 

func CleanCommands(commandsPaths []string, dryRun bool) ([]string, error)

CleanCommands removes ttal-managed command files that no longer exist in source paths.

func CleanRules added in v1.0.0 

func CleanRules(rulesPaths []string, dryRun bool) ([]string, error)

CleanRules removes rule files from a rules directory that don't correspond to any RULE.md found in the configured rules_paths.

func CleanRulesIn added in v1.0.0 

func CleanRulesIn(rulesPaths []string, rulesDir string, dryRun bool) ([]string, error)

CleanRulesIn removes rule files from rulesDir that don't correspond to any RULE.md found in the configured rules_paths.

func CleanSkills 

func CleanSkills(skillsPaths []string, dryRun bool) ([]string, error)

CleanSkills removes directories in ~/.claude/skills/ and ~/.codex/skills/ that no longer correspond to any skill in any skills_paths source.

func DenyPrimaryAgentsAsSubagents added in v1.3.0 

func DenyPrimaryAgentsAsSubagents(agentNames []string, dryRun bool) (added []string, err error)

DenyPrimaryAgentsAsSubagents reads ~/.claude/settings.json and ensures Agent(<name>) deny entries exist for all deployed agents, preventing CC from spawning them directly as subagents. All agent routing must go through ttal task route.

Additive only — appends new entries at the end of the deny list, never removes or reorders existing entries. Returns list of newly added entry names.

func DeployCodexAgents 

func DeployCodexAgents(agents []*ParsedAgent, dryRun bool) error

DeployCodexAgents writes per-agent .toml files and merges registration entries into config.toml.

func DeployCodexRules added in v1.0.0 

func DeployCodexRules(rules []RuleResult, dryRun bool) error

DeployCodexRules aggregates all RULE.md contents into ~/.codex/AGENTS.md under a managed section delimited by HTML comment markers.

func DeployCodexRulesTo added in v1.0.0 

func DeployCodexRulesTo(rules []RuleResult, agentsPath string, dryRun bool) error

DeployCodexRulesTo writes aggregated rules to a specific AGENTS.md path. Used by tests to avoid touching ~/.codex/AGENTS.md.

func GenerateCCCommandVariant 

func GenerateCCCommandVariant(cmd *ParsedCommand) (string, error)

GenerateCCCommandVariant produces a CC skill SKILL.md from a parsed canonical command. Includes shared fields (description, argument-hint) plus claude-code specific fields.

func GenerateCCVariant 

func GenerateCCVariant(agent *ParsedAgent) (string, error)

GenerateCCVariant produces a Claude Code agent .md file from a parsed canonical agent. Includes shared fields (name, description) plus claude-code specific fields.

func GenerateCodexVariant 

func GenerateCodexVariant(agent *ParsedAgent) string

GenerateCodexVariant produces a Codex agent .toml file content from a parsed canonical agent. The markdown body becomes developer_instructions; optional codex: frontmatter fields are merged.

func GenerateOCCommandVariant 

func GenerateOCCommandVariant(cmd *ParsedCommand) (string, error)

GenerateOCCommandVariant produces an OC command .md from a parsed canonical command. Includes shared fields (description, argument-hint) plus opencode specific fields.

func GenerateOCVariant 

func GenerateOCVariant(agent *ParsedAgent) (string, error)

GenerateOCVariant produces an OpenCode agent .md file from a parsed canonical agent. Includes shared fields (name, description) plus opencode specific fields.

Types

type AgentFrontmatter 

type AgentFrontmatter struct {
	Name        string                 `yaml:"name"`
	Description string                 `yaml:"description"`
	Emoji       string                 `yaml:"emoji"`
	ClaudeCode  map[string]interface{} `yaml:"claude-code"`
	OpenCode    map[string]interface{} `yaml:"opencode"`
	Codex       map[string]interface{} `yaml:"codex"`
	Ttal        *TtalAgentConfig       `yaml:"ttal"`
}

AgentFrontmatter holds parsed frontmatter from a canonical agent .md file.

type AgentResult 

type AgentResult struct {
	Source    string
	Name      string
	CCDest    string
	OCDest    string // Deprecated: kept for sync compatibility
	CodexDest string
}

AgentResult tracks a single agent deployment for reporting.

func DeployAgents 

func DeployAgents(subagentsPaths []string, dryRun bool) ([]AgentResult, error)

DeployAgents reads canonical agent .md files from the given paths and deploys runtime-specific variants to Claude Code, OpenCode, and Codex agent directories.

type CommandFrontmatter 

type CommandFrontmatter struct {
	Name         string                 `yaml:"name"`
	Description  string                 `yaml:"description"`
	ArgumentHint string                 `yaml:"argument-hint"`
	ClaudeCode   map[string]interface{} `yaml:"claude-code"`
	OpenCode     map[string]interface{} `yaml:"opencode"`
}

CommandFrontmatter holds parsed frontmatter from a canonical command .md file.

type CommandResult 

type CommandResult struct {
	Source    string
	Name      string
	CCDest    string
	OCDest    string
	CodexDest string
}

CommandResult tracks a single command deployment for reporting.

func DeployCommands 

func DeployCommands(commandsPaths []string, dryRun bool) ([]CommandResult, error)

DeployCommands reads canonical command .md files from the given paths and deploys runtime-specific variants to Claude Code (as skills) and OpenCode (as commands).

type GlobalPromptResult 

type GlobalPromptResult struct {
	Source  string
	Dest    string
	Runtime string
}

GlobalPromptResult tracks a single global prompt deployment for reporting.

func DeployGlobalPrompt 

func DeployGlobalPrompt(rawPath string, dryRun bool) ([]GlobalPromptResult, error)

DeployGlobalPrompt copies one canonical global prompt markdown file into runtime paths. Always targets Claude Code (~/.claude/CLAUDE.md), and additionally targets Codex (~/.codex/AGENTS.md) when ~/.codex exists and is a directory.

type ParsedAgent 

type ParsedAgent struct {
	Frontmatter AgentFrontmatter
	Body        string
}

ParsedAgent holds the parsed frontmatter and body of an agent .md file.

func DiscoverTtalAgents added in v1.1.0 

func DiscoverTtalAgents(subagentsPaths []string) ([]*ParsedAgent, error)

DiscoverTtalAgents scans subagents_paths for .md files with ttal: frontmatter. Returns only agents that have a ttal: section, sorted by name.

func ParseAgentFile 

func ParseAgentFile(content string) (*ParsedAgent, error)

ParseAgentFile splits a canonical agent .md file into frontmatter and body. Expected format: 

---
name: foo
...
---
Body text here

type ParsedCommand 

type ParsedCommand struct {
	Frontmatter CommandFrontmatter
	Body        string
}

ParsedCommand holds the parsed frontmatter and body of a command .md file.

func ParseCommandFile 

func ParseCommandFile(content string) (*ParsedCommand, error)

ParseCommandFile splits a canonical command .md file into frontmatter and body. Expected format: 

---
name: foo
description: Short description
...
---
Body text here

type RuleResult added in v1.0.0 

type RuleResult struct {
	Source string // Full path to RULE.md
	Name   string // Rule name (directory name)
	Dest   string // ~/.claude/rules/{name}.md
}

RuleResult records one RULE.md deployment.

func DeployRules added in v1.0.0 

func DeployRules(rulesPaths []string, dryRun bool) ([]RuleResult, error)

DeployRules scans rules_paths for directories containing RULE.md and copies them to ~/.claude/rules/{name}.md.

func DeployRulesTo added in v1.0.0 

func DeployRulesTo(rulesPaths []string, rulesDir string, dryRun bool) ([]RuleResult, error)

DeployRulesTo is like DeployRules but writes to a custom destination directory. Used by tests to avoid touching ~/.claude/rules/.

type SkillResult 

type SkillResult struct {
	Source    string
	Name      string
	Dest      string // CC destination (~/.claude/skills/)
	CodexDest string // Codex destination (~/.codex/skills/)
}

SkillResult tracks a single skill deployment for reporting.

func DeploySkills 

func DeploySkills(skillsPaths []string, dryRun bool) ([]SkillResult, error)

DeploySkills copies skill directories (those containing SKILL.md) to ~/.claude/skills/ (CC) and ~/.codex/skills/ (Codex).

type TtalAgentConfig added in v1.1.0 

type TtalAgentConfig struct {
	Model string   `yaml:"model"`
	Tools []string `yaml:"tools"`
}

TtalAgentConfig holds ttal-native execution config for a subagent. When present, ttal can run the agent directly without manual --tool/--model flags.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.