[fix] Make agent file installation opt-in on rimba init (#69)

* [fix] Replace non-existent `rimba cd` with `rimba open` in agent files

The generated agent instruction files referenced `rimba cd`, which was
never a real command. Replace all occurrences with `rimba open` in the
template source (content.go) and regenerated outputs. Also update the
`rimba init` docs to mention agent file installation.

* [fix] Make agent file installation opt-in via --agent-files flag

rimba init no longer installs AI agent instruction files by default.
Users must pass --agent-files to opt in.

Author: lugassawan

.claude/skills/rimba/SKILL.md

@@ -21,7 +21,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 | Start a new task | `rimba add <task>` |
 | See all worktrees | `rimba list` or `rimba list --json` |
 | Check worktree health | `rimba status` |
-| Navigate to a worktree | `cd $(rimba cd <task>)` |
+| Navigate to a worktree | `cd $(rimba open <task>)` |
 | Update from source branch | `rimba sync <task>` or `rimba sync` (all) |
 | Finish a feature | `rimba merge <task>` then `rimba remove <task>` |
 | Clean up merged work | `rimba clean --merged` |

.cursor/rules/rimba.mdc

@@ -15,7 +15,7 @@ See AGENTS.md at the repo root for full documentation.
 1. `rimba add <task>` — create worktree + branch
 2. `rimba list` — list all worktrees
 3. `rimba status` — health overview (dirty, stale, behind)
-4. `rimba cd <task>` — print path for cd
+4. `rimba open <task>` — print path or run shortcut (--ide, --agent)
 5. `rimba sync [task]` — rebase worktree(s) onto source
 6. `rimba merge <task>` — fast-forward merge into source
 7. `rimba remove <task>` — delete worktree + branch

AGENTS.md

@@ -20,7 +20,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 
 | Concern | Commands |
 |---------|----------|
-| Create & navigate | `rimba add <task>`, `rimba open <task>`, `rimba cd <task>` |
+| Create & navigate | `rimba add <task>`, `rimba open <task>` |
 | Inspect | `rimba list`, `rimba status`, `rimba log [task]` |
 | Sync & merge | `rimba sync [task]`, `rimba merge <task>` |
 | Clean up | `rimba clean --merged`, `rimba archive <task>`, `rimba remove <task>` |
@@ -31,7 +31,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 **Create a worktree and start working:**
 ```sh
 rimba add my-feature        # creates worktree + branch
-rimba cd my-feature         # prints cd command (use: cd $(rimba cd my-feature))
+rimba open my-feature       # prints worktree path (use: cd $(rimba open my-feature))
 ```
 
 **Check health and clean up stale worktrees:**

cmd/init.go

@@ -12,14 +12,17 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const flagAgentFiles = "agent-files"
+
 func init() {
 	rootCmd.AddCommand(initCmd)
+	initCmd.Flags().Bool(flagAgentFiles, false, "Install AI agent instruction files (AGENTS.md, copilot, cursor, claude)")
 }
 
 var initCmd = &cobra.Command{
 	Use:         "init",
 	Short:       "Initialize rimba in the current repository",
-	Long:        "Detects the repository root, creates a .rimba.toml config file, sets up the worktree directory, and installs agent instruction files.",
+	Long:        "Detects the repository root, creates a .rimba.toml config file, and sets up the worktree directory. Use --agent-files to also install AI agent instruction files.",
 	Annotations: map[string]string{"skipConfig": "true"},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		r := newRunner()
@@ -76,13 +79,16 @@ var initCmd = &cobra.Command{
 			fmt.Fprintf(cmd.OutOrStdout(), "Config %s already exists, skipping config creation\n", configPath)
 		}
 
-		// Install agent instruction files
-		results, err := agentfile.Install(repoRoot)
-		if err != nil {
-			return fmt.Errorf("install agent files: %w", err)
-		}
-		for _, res := range results {
-			fmt.Fprintf(cmd.OutOrStdout(), "  Agent:        %s (%s)\n", res.RelPath, res.Action)
+		// Install agent instruction files if requested
+		installAgentFiles, _ := cmd.Flags().GetBool(flagAgentFiles)
+		if installAgentFiles {
+			results, err := agentfile.Install(repoRoot)
+			if err != nil {
+				return fmt.Errorf("install agent files: %w", err)
+			}
+			for _, res := range results {
+				fmt.Fprintf(cmd.OutOrStdout(), "  Agent:        %s (%s)\n", res.RelPath, res.Action)
+			}
 		}
 
 		return nil

cmd/init_test.go

@@ -73,6 +73,7 @@ func TestInitCreatesAgentFiles(t *testing.T) {
 	defer restore()
 
 	cmd, buf := newTestCmd()
+	cmd.Flags().Bool(flagAgentFiles, true, "")
 
 	if err := initCmd.RunE(cmd, nil); err != nil {
 		t.Fatalf("initCmd.RunE: %v", err)
@@ -124,6 +125,7 @@ func TestInitExistingConfigInstallsAgentFiles(t *testing.T) {
 	defer restore()
 
 	cmd, buf := newTestCmd()
+	cmd.Flags().Bool(flagAgentFiles, true, "")
 
 	// Should succeed (not error) when .rimba.toml already exists
 	err := initCmd.RunE(cmd, nil)
@@ -162,12 +164,14 @@ func TestInitAgentFilesIdempotent(t *testing.T) {
 
 	// First init
 	cmd1, _ := newTestCmd()
+	cmd1.Flags().Bool(flagAgentFiles, true, "")
 	if err := initCmd.RunE(cmd1, nil); err != nil {
 		t.Fatalf("first initCmd.RunE: %v", err)
 	}
 
 	// Second init (config exists now)
 	cmd2, buf2 := newTestCmd()
+	cmd2.Flags().Bool(flagAgentFiles, true, "")
 	if err := initCmd.RunE(cmd2, nil); err != nil {
 		t.Fatalf("second initCmd.RunE: %v", err)
 	}
@@ -187,6 +191,40 @@ func TestInitAgentFilesIdempotent(t *testing.T) {
 	}
 }
 
+func TestInitWithoutFlagSkipsAgentFiles(t *testing.T) {
+	repoDir := t.TempDir()
+
+	r := &mockRunner{
+		run: func(args ...string) (string, error) {
+			if len(args) >= 2 && args[1] == cmdShowToplevel {
+				return repoDir, nil
+			}
+			if len(args) >= 1 && args[0] == cmdSymbolicRef {
+				return refsRemotesOriginMain, nil
+			}
+			return "", nil
+		},
+		runInDir: noopRunInDir,
+	}
+	restore := overrideNewRunner(r)
+	defer restore()
+
+	cmd, buf := newTestCmd()
+
+	if err := initCmd.RunE(cmd, nil); err != nil {
+		t.Fatalf("initCmd.RunE: %v", err)
+	}
+
+	out := buf.String()
+	if strings.Contains(out, "Agent:") {
+		t.Errorf("output should not mention agent files without --agent-files flag, got:\n%s", out)
+	}
+
+	if _, err := os.Stat(filepath.Join(repoDir, "AGENTS.md")); err == nil {
+		t.Error("AGENTS.md should not be created without --agent-files flag")
+	}
+}
+
 func TestInitRepoRootError(t *testing.T) {
 	r := &mockRunner{
 		run: func(args ...string) (string, error) {

docs/commands.md

@@ -19,12 +19,19 @@ These flags are available on every command via the root `rimba` command:
 
 ### rimba init
 
-Initialize rimba in the current repository. Detects the repo root, creates `.rimba.toml`, and sets up the worktree directory.
+Initialize rimba in the current repository. Detects the repo root, creates `.rimba.toml`, and sets up the worktree directory. Use `--agent-files` to also install AI agent instruction files (`AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/rimba.mdc`, `.claude/skills/rimba/SKILL.md`).
+
+If `.rimba.toml` already exists, config creation is skipped but agent files are still installed or updated when `--agent-files` is passed.
 
 ```sh
-rimba init
+rimba init                  # Initialize config and worktree directory
+rimba init --agent-files    # Also install AI agent instruction files
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--agent-files` | Install AI agent instruction files (AGENTS.md, copilot, cursor, claude) |
+
 ---
 
 ## Worktree Lifecycle

internal/agentfile/content.go

@@ -27,7 +27,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 
 | Concern | Commands |
 |---------|----------|
-| Create & navigate | ` + "`" + `rimba add <task>` + "`" + `, ` + "`" + `rimba open <task>` + "`" + `, ` + "`" + `rimba cd <task>` + "`" + ` |
+| Create & navigate | ` + "`" + `rimba add <task>` + "`" + `, ` + "`" + `rimba open <task>` + "`" + ` |
 | Inspect | ` + "`" + `rimba list` + "`" + `, ` + "`" + `rimba status` + "`" + `, ` + "`" + `rimba log [task]` + "`" + ` |
 | Sync & merge | ` + "`" + `rimba sync [task]` + "`" + `, ` + "`" + `rimba merge <task>` + "`" + ` |
 | Clean up | ` + "`" + `rimba clean --merged` + "`" + `, ` + "`" + `rimba archive <task>` + "`" + `, ` + "`" + `rimba remove <task>` + "`" + ` |
@@ -38,7 +38,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 **Create a worktree and start working:**
 ` + "```" + `sh
 rimba add my-feature        # creates worktree + branch
-rimba cd my-feature         # prints cd command (use: cd $(rimba cd my-feature))
+rimba open my-feature       # prints worktree path (use: cd $(rimba open my-feature))
 ` + "```" + `
 
 **Check health and clean up stale worktrees:**
@@ -123,7 +123,7 @@ See AGENTS.md at the repo root for full documentation.
 1. ` + "`" + `rimba add <task>` + "`" + ` — create worktree + branch
 2. ` + "`" + `rimba list` + "`" + ` — list all worktrees
 3. ` + "`" + `rimba status` + "`" + ` — health overview (dirty, stale, behind)
-4. ` + "`" + `rimba cd <task>` + "`" + ` — print path for cd
+4. ` + "`" + `rimba open <task>` + "`" + ` — print path or run shortcut (--ide, --agent)
 5. ` + "`" + `rimba sync [task]` + "`" + ` — rebase worktree(s) onto source
 6. ` + "`" + `rimba merge <task>` + "`" + ` — fast-forward merge into source
 7. ` + "`" + `rimba remove <task>` + "`" + ` — delete worktree + branch
@@ -175,7 +175,7 @@ curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/insta
 | Start a new task | ` + "`" + `rimba add <task>` + "`" + ` |
 | See all worktrees | ` + "`" + `rimba list` + "`" + ` or ` + "`" + `rimba list --json` + "`" + ` |
 | Check worktree health | ` + "`" + `rimba status` + "`" + ` |
-| Navigate to a worktree | ` + "`" + `cd $(rimba cd <task>)` + "`" + ` |
+| Navigate to a worktree | ` + "`" + `cd $(rimba open <task>)` + "`" + ` |
 | Update from source branch | ` + "`" + `rimba sync <task>` + "`" + ` or ` + "`" + `rimba sync` + "`" + ` (all) |
 | Finish a feature | ` + "`" + `rimba merge <task>` + "`" + ` then ` + "`" + `rimba remove <task>` + "`" + ` |
 | Clean up merged work | ` + "`" + `rimba clean --merged` + "`" + ` |

tests/e2e/init_test.go

@@ -60,10 +60,10 @@ func TestInitExistingConfigInstallsAgentFiles(t *testing.T) {
 	}
 
 	repo := setupRepo(t)
-	rimbaSuccess(t, repo, "init")
+	rimbaSuccess(t, repo, "init", "--agent-files")
 
 	// Re-running init should succeed and update agent files
-	r := rimbaSuccess(t, repo, "init")
+	r := rimbaSuccess(t, repo, "init", "--agent-files")
 	assertContains(t, r.Stdout, "already exists")
 	assertContains(t, r.Stdout, "Agent:")
 }
@@ -126,6 +126,33 @@ func TestInitFailsOutsideGitRepo(t *testing.T) {
 	rimbaFail(t, dir, "init")
 }
 
+func TestInitWithAgentFilesFlag(t *testing.T) {
+	if testing.Short() {
+		t.Skip(skipE2E)
+	}
+
+	repo := setupRepo(t)
+	r := rimbaSuccess(t, repo, "init", "--agent-files")
+
+	assertContains(t, r.Stdout, "Agent:")
+	assertFileExists(t, filepath.Join(repo, "AGENTS.md"))
+	assertFileExists(t, filepath.Join(repo, ".github", "copilot-instructions.md"))
+	assertFileExists(t, filepath.Join(repo, ".cursor", "rules", "rimba.mdc"))
+	assertFileExists(t, filepath.Join(repo, ".claude", "skills", "rimba", "SKILL.md"))
+}
+
+func TestInitSkipsAgentFilesWithoutFlag(t *testing.T) {
+	if testing.Short() {
+		t.Skip(skipE2E)
+	}
+
+	repo := setupRepo(t)
+	r := rimbaSuccess(t, repo, "init")
+
+	assertNotContains(t, r.Stdout, "Agent:")
+	assertFileNotExists(t, filepath.Join(repo, "AGENTS.md"))
+}
+
 // assertGitignoreContains verifies that .gitignore in the repo contains the given entry.
 func assertGitignoreContains(t *testing.T, repo, entry string) {
 	t.Helper()