Documentation
¶
Index ¶
- Constants
- Variables
- func EnsureMCPConfig(projectRoot, ideID string) (string, error)
- func EnsureRulesForIDE(projectRoot string, detected DetectedIDE) ([]string, error)
- func EnsureRulesWithAIConsent(projectRoot string, detected DetectedIDE, interactive bool, appVersion string, ...) ([]string, error)
- func Generate(projectRoot, ideType string) ([]string, error)
- func MCPConfigExists(projectRoot, ideID string) bool
- func RemoveConsent(projectRoot string) error
- func RemoveRulesForIDE(projectRoot string, detected DetectedIDE) ([]string, error)
- func SetForceRuleWrite(v bool)
- func SetGeneratorVersion(version string)
- type DetectedIDE
- type EnsureOptions
Constants ¶
const ( IDECursor = "cursor" IDEVSCode = "vscode" IDECopilot = "copilot" // vscode + copilot IDEClaudeCode = "claude-code" IDEWindsurf = "windsurf" IDECline = "cline" IDEZed = "zed" IDENeovim = "neovim" IDEJetBrains = "jetbrains" IDEUnknown = "unknown" IDEBoth = "both" // legacy: cursor + copilot )
IDE type constants
const GitflowInstructionsCompact = `## Gitflow Enforcement
**Before modifying ANY code, run the gitflow pre-flight check.**
` + "```bash" + `
gitflow --json status
` + "```" + `
### Pre-flight sequence
1. Check ` + "`git_flow_initialized`" + ` → if false, run ` + "`gitflow --json init`" + `
2. Check ` + "`merge.in_merge`" + ` → if true, STOP and report to user
3. Check ` + "`main_ahead_of_develop`" + ` → if > 0, run ` + "`gitflow --json backmerge`" + `
4. Ensure you are on the correct branch for the task type
5. NEVER modify code on main or develop directly — use flow branches
6. When done: ` + "`gitflow --json finish`" + `
### Branch routing
| Task type | Start command |
|-------------|----------------------------------------------|
| Feature | ` + "`gitflow --json start feature <name>`" + ` |
| Bugfix | ` + "`gitflow --json start bugfix <name>`" + ` |
| Hotfix | ` + "`gitflow --json start hotfix <version>`" + ` |
| Release | ` + "`gitflow --json start release <version>`" + ` |
### Skill Activation (Homologated)
- Use the gitflow skill before any code modifications.
- Always begin with ` + "`gitflow --json status`" + `.
- Keep command selection aligned with task intent and branch type.
### LLM Activity Routing (Compact)
- discovery/state -> ` + "`gitflow --json status`" + `
- branch divergence -> ` + "`gitflow --json backmerge`" + `
- new work -> ` + "`gitflow --json start feature <name>`" + `
- bug fix -> ` + "`gitflow --json start bugfix <name>`" + `
- prod urgent fix -> ` + "`gitflow --json start hotfix <version>`" + `
- release prep -> ` + "`gitflow --json start release <version>`" + `
- branch sync/update -> ` + "`gitflow --json sync`" + ` / ` + "`gitflow --json pull`" + `
- diagnostics -> ` + "`gitflow --json health`" + ` / ` + "`gitflow --json doctor`" + `
- rollback last flow action -> ` + "`gitflow --json undo`" + `
- close flow branch -> ` + "`gitflow --json finish`" + `
### Full CLI
` + "```" + `
gitflow --json status|pull|init|sync|switch|backmerge|cleanup|health|doctor|log|undo|releasenotes|diagram|finish
gitflow --json start feature|bugfix|release|hotfix <name>
` + "```" + `
Exit codes: 0=success, 1=error, 2=conflict-needs-human
`
GitflowInstructionsCompact is a shorter version for IDEs with limited instruction space (e.g. appended sections in existing files).
const GitflowInstructionsFull = `## Gitflow Pre-flight Check
**MANDATORY: Before modifying ANY code, run the pre-flight check.**
### Step 1 — Run status (EVERY TIME before code changes)
` + "```bash" + `
gitflow --json status
` + "```" + `
Evaluate the JSON response in order:
#### 1a. Is git-flow initialized?
If ` + "`git_flow_initialized`" + ` is false:
` + "```bash" + `
gitflow --json init
` + "```" + `
#### 1b. Is there a merge conflict?
If ` + "`merge.in_merge`" + ` is true → **STOP.** Report to user.
#### 1c. Is there branch divergence?
If ` + "`main_ahead_of_develop > 0`" + ` → **STOP.** Fix immediately:
` + "```bash" + `
gitflow --json backmerge
` + "```" + `
#### 1d. Are we on the right branch?
| User wants to... | Correct branch | If wrong, run |
|---------------------------|-------------------------|--------------------------------------------|
| Add a new feature | feature/* or develop | ` + "`gitflow --json switch develop`" + `, then ` + "`gitflow --json start feature <name>`" + ` |
| Fix a bug (non-urgent) | bugfix/* or develop | ` + "`gitflow --json switch develop`" + `, then ` + "`gitflow --json start bugfix <name>`" + ` |
| Fix a production bug | hotfix/* or main | ` + "`gitflow --json switch main`" + `, then ` + "`gitflow --json start hotfix <ver>`" + ` |
| Prepare a release | release/* or develop | ` + "`gitflow --json switch develop`" + `, then ` + "`gitflow --json start release <ver>`" + ` |
**NEVER modify code on main. NEVER commit directly to develop.**
#### 1e. Ask user intent
If no flow branch exists, ask the user:
1. Feature — new functionality
2. Bugfix — fix a non-urgent bug
3. Hotfix — urgent fix for production
4. Continue — already on the right branch
#### 1f. Only NOW proceed with code changes
### Step 2 — During Development
` + "```bash" + `
gitflow --json sync # sync with parent
gitflow --json pull # pull before pushing
` + "```" + `
### Step 3 — Finishing Work
` + "```bash" + `
gitflow --json finish
` + "```" + `
### Skill Activation (Homologated)
- Use the gitflow skill before any code modifications.
- Run ` + "`gitflow --json status`" + ` first and follow branch/merge checks.
- Keep branch routing aligned with the skill decision tree.
### LLM Activity Routing (Command Selection)
Use this mapping to choose commands according to model interaction intent.
| Interaction intent | Primary command(s) | Use when |
|---|---|---|
| Understand current gitflow state | ` + "`gitflow --json status`" + ` | Start of every coding task; validate branch/divergence/merge state |
| Initialize git-flow in repo | ` + "`gitflow --json init`" + ` | ` + "`git_flow_initialized`" + ` is false |
| Resolve main/develop divergence | ` + "`gitflow --json backmerge`" + ` | ` + "`main_ahead_of_develop > 0`" + ` |
| Start feature work | ` + "`gitflow --json start feature <name>`" + ` | New capability or enhancement |
| Start non-urgent bug fix | ` + "`gitflow --json start bugfix <name>`" + ` | Defect that is not production-emergency |
| Start production fix | ` + "`gitflow --json start hotfix <version>`" + ` | Urgent issue in production/main |
| Start release preparation | ` + "`gitflow --json start release <version>`" + ` | Cut release candidate and stabilize |
| Sync active work branch | ` + "`gitflow --json sync`" + ` | Before big changes and before final validation |
| Pull latest updates | ` + "`gitflow --json pull`" + ` | Keep branch current before push/finish |
| Run health diagnostics | ` + "`gitflow --json health`" + `, ` + "`gitflow --json doctor`" + ` | User reports workflow inconsistency/conflicts |
| Review timeline / history | ` + "`gitflow --json log`" + ` | Need operational trace or audit trail |
| Undo last gitflow action | ` + "`gitflow --json undo`" + ` | Last operation was wrong and needs rollback |
| Finish current flow branch | ` + "`gitflow --json finish`" + ` | Tests pass and branch is ready to merge |
### CLI Reference
` + "```" + `
gitflow --json status|pull|init|sync|switch|backmerge|cleanup|health|doctor|log|undo|releasenotes|diagram|finish
gitflow --json start feature|bugfix|release|hotfix <name>
gitflow setup [--ide cursor|copilot|both]
` + "```" + `
Exit codes: 0=success, 1=error, 2=conflict-needs-human
`
GitflowInstructionsFull is the complete gitflow preflight instruction set, reusable across all IDE rule generators. It uses pure markdown (no IDE-specific frontmatter) so each generator can wrap it as needed.
Variables ¶
var AskAIIntegrationFunc = askAIIntegration
var MCPSupportedIDEs = map[string]bool{ IDECursor: true, IDECopilot: true, IDEVSCode: true, IDEClaudeCode: true, IDEWindsurf: true, IDECline: true, IDEZed: true, IDENeovim: true, IDEJetBrains: true, }
MCPSupportedIDEs lists IDE IDs that support MCP server configuration.
var UserHomeDirFunc = os.UserHomeDir
Functions ¶
func EnsureMCPConfig ¶
EnsureMCPConfig creates or updates the MCP config file for the given IDE, adding a gitflow server entry if not already present. Returns the file path if created/updated, or empty string if already present or IDE unsupported.
func EnsureRulesForIDE ¶
func EnsureRulesForIDE(projectRoot string, detected DetectedIDE) ([]string, error)
EnsureRulesForIDE checks if rules exist for the detected IDE and any detected companion IDEs. For the primary it creates rules if missing, ensures the embedded gitflow skill, AGENTS.md (for non-project-skill IDEs), and MCP config (where supported). After the primary it recursively provisions any IDE returned by companionIDEs() whose detectXxx() returns true in the same environment.
Recursion is bounded by a processed-set; a companion whose id equals the primary is skipped.
Returns list of newly created files (empty if all exist or on second idempotent run).
func EnsureRulesWithAIConsent ¶
func EnsureRulesWithAIConsent(projectRoot string, detected DetectedIDE, interactive bool, appVersion string, opts ...EnsureOptions) ([]string, error)
EnsureRulesWithAIConsent installs IDE-specific instructions and embedded skill only when user consent for AI integration is enabled.
Consent is persisted at {projectRoot}/.gitflow/config.json (per project). In non-interactive mode (agents / --json) this function does NOT auto-enable unless opts.AutoAccept is set; it skips provisioning when no prior consent exists, preserving explicit user opt-in.
When consent exists, provisioning runs only when appVersion is unknown, no stored version exists yet, or the running appVersion is newer than the stored version. Otherwise, file I/O is skipped (unless opts.Force).
func Generate ¶
Generate dispatches to the appropriate rule/instruction file generators. For explicit setup: always generates for the specified IDE, installs the embedded skill, ensures AGENTS.md, and writes MCP config when supported.
For Cursor-family primaries (cursor, vscode, copilot), Generate also installs any companion IDEs returned by companionIDEs() (e.g. Claude Code when detected in the same environment). The "both" and "unknown" branches keep their original multi-IDE fan-out behavior.
func MCPConfigExists ¶
MCPConfigExists checks whether an MCP config with a gitflow entry already exists.
func RemoveConsent ¶ added in v0.7.0
RemoveConsent deletes the AI integration choice entry from the project's .gitflow/config.json (or no-ops if absent).
func RemoveRulesForIDE ¶ added in v0.7.0
func RemoveRulesForIDE(projectRoot string, detected DetectedIDE) ([]string, error)
RemoveRulesForIDE is the inverse of EnsureRulesForIDE: it deletes the IDE-specific rule file, MCP config, project-scoped skill, and (for non-project-skill IDEs) the AGENTS.md universal fallback. It mirrors the companion-aware recursion so uninstalling the primary also removes any companion artifacts (e.g. Cursor uninstall removes Claude Code companion files too). Returns the list of paths that were removed.
func SetForceRuleWrite ¶ added in v0.7.0
func SetForceRuleWrite(v bool)
SetForceRuleWrite toggles the package-level force flag. The setup command uses this with a defer to scope the flag to a single invocation.
func SetGeneratorVersion ¶ added in v0.6.2
func SetGeneratorVersion(version string)
Types ¶
type DetectedIDE ¶
DetectedIDE holds the result of IDE detection with display-friendly name.
func DetectAll ¶
func DetectAll(projectRoot string) []DetectedIDE
DetectAll returns all detected IDEs (there may be multiple signals).
func DetectPrimary ¶
func DetectPrimary(projectRoot string) DetectedIDE
DetectPrimary returns the most specific IDE detected, or "unknown".
type EnsureOptions ¶ added in v0.7.0
type EnsureOptions struct {
// AutoAccept skips the consent dialog on first run. Used by `gitflow
// setup --yes` for non-interactive agents and CI.
AutoAccept bool
// Force re-writes all artifacts even when their content matches the
// expected byte stream (bypasses the idempotency check in
// ensureEmbeddedSkill and the cursor rule's content-equality guard).
Force bool
// CheckOnly computes what would be created or removed without writing
// to disk. Returned slice is the list of paths that WOULD be created
// on a real run.
CheckOnly bool
}
EnsureOptions controls behavior of EnsureRulesWithAIConsent. Zero value is the default (interactive consent, no force, no dry-run). Pass as the optional last argument; omitting it preserves backward compatibility.
Source Files