feat: add efctl usage instructions to AGENTS.md and implement --ai flag for init

Author: Scetrov

.agents/instructions.md

@@ -0,0 +1,14 @@
+<!-- EFCTL_INSTRUCTIONS_START -->
+# efctl Context
+You are working on a project using 'efctl', the EVE Frontier CLI.
+Reference AGENTS.md for core principles.
+
+## efctl Commands
+- Init: efctl init
+- Up: efctl env up
+- Down: efctl env down
+- Status: efctl env status
+- Publish Extension: efctl env extension publish [path]
+- Query World: efctl world query [object_id]
+<!-- EFCTL_INSTRUCTIONS_END -->
+Extra text

AGENTS.md

@@ -46,3 +46,15 @@ To maintain a non-breaking flow and avoid permission requests:
 - Keep terminal usage limited to short operational commands such as `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, and install commands.
 - Keep responses concise and write substantial artifacts to files instead of long inline output.
 - Utility commands: `ctx stats`, `ctx doctor`, `ctx upgrade`.
+
+## 8. Development Cheat Sheet
+
+Quick reference for common `efctl` operations:
+
+- **Initialize configuration**: `efctl init` (or `efctl init --ai [agent]`)
+- **Environment Lifecycle**:
+  - Up: `efctl env up`
+  - Down: `efctl env down`
+- **Status Check**: `efctl env status`
+- **Deploy Extension**: `efctl env extension publish [contract-path]` (path defaults to `./my-extension`)
+- **Query World**: `efctl world query [object_id]` (queries the Sui GraphQL RPC)

cmd/init.go

@@ -8,12 +8,14 @@ import (
 	"path/filepath"
 	"strings"
 
+	"efctl/pkg/builder"
 	"efctl/pkg/config"
 	"efctl/pkg/ui"
 	"github.com/spf13/cobra"
 )
 
 var initForce bool
+var initAiAgent string
 
 var initCmd = &cobra.Command{
 	Use:   "init",
@@ -74,6 +76,15 @@ var initCmd = &cobra.Command{
 			ui.Success.Println("Created example extension directory")
 		}
 
+		// 4. AI Instructions
+		if initAiAgent != "" {
+			if err := builder.SetupAIInstructions(initAiAgent, targetDir); err != nil {
+				ui.Warn.Printf("Failed to setup AI instructions: %v\n", err)
+			} else {
+				ui.Success.Printf("Setup AI instructions for %s\n", initAiAgent)
+			}
+		}
+
 		return nil
 	},
 }
@@ -137,5 +148,6 @@ func readGitignore(path string) (map[string]bool, error) {
 
 func init() {
 	initCmd.Flags().BoolVar(&initForce, "force", false, "Overwrite an existing config file")
+	initCmd.Flags().StringVar(&initAiAgent, "ai", "", "Setup AI instructions for a specific agent (copilot, claude, gemini)")
 	rootCmd.AddCommand(initCmd)
 }

docs/efctl_init.md

@@ -13,8 +13,9 @@ efctl init [flags]
 ### Options
 
 ```
-      --force   Overwrite an existing config file
-  -h, --help    help for init
+      --ai string   Setup AI instructions for a specific agent (copilot, claude, gemini)
+      --force       Overwrite an existing config file
+  -h, --help        help for init
 ```
 
 ### Options inherited from parent commands

pkg/builder/ai.go

@@ -0,0 +1,89 @@
+package builder
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const (
+	MarkerStart = "<!-- EFCTL_INSTRUCTIONS_START -->"
+	MarkerEnd   = "<!-- EFCTL_INSTRUCTIONS_END -->"
+)
+
+// SetupAIInstructions configures instructions for various AI agents idempotently.
+func SetupAIInstructions(agentName string, workspace string) error {
+	var targetFile string
+	var instructions string
+
+	agentName = strings.ToLower(agentName)
+
+	switch agentName {
+	case "copilot", "cursor":
+		targetFile = ".cursorrules"
+		instructions = getCopilotInstructions()
+	case "claude":
+		targetFile = ".clauderules"
+		instructions = getClaudeInstructions()
+	case "gemini":
+		targetFile = filepath.Join(".agents", "instructions.md")
+		instructions = getGeminiInstructions()
+	default:
+		return fmt.Errorf("unsupported agent: %s; supported agents are: copilot, claude, gemini", agentName)
+	}
+
+	absPath := filepath.Join(workspace, targetFile)
+	targetDir := filepath.Dir(absPath)
+	if err := os.MkdirAll(targetDir, 0750); err != nil {
+		return fmt.Errorf("failed to create directory for %s: %w", targetFile, err)
+	}
+
+	content := fmt.Sprintf("\n%s\n%s\n%s\n", MarkerStart, strings.TrimSpace(instructions), MarkerEnd)
+
+	existing, err := os.ReadFile(absPath) // #nosec G304
+	if err != nil {
+		if os.IsNotExist(err) {
+			return os.WriteFile(absPath, []byte(strings.TrimSpace(content)+"\n"), 0600) // #nosec G306 G703
+		}
+		return err
+	}
+
+	existingStr := string(existing)
+	startIdx := strings.Index(existingStr, MarkerStart)
+	endIdx := strings.Index(existingStr, MarkerEnd)
+
+	if startIdx != -1 && endIdx != -1 && endIdx > startIdx {
+		// Replace existing block
+		newContent := existingStr[:startIdx] + strings.TrimSpace(content) + existingStr[endIdx+len(MarkerEnd):]
+		return os.WriteFile(absPath, []byte(newContent), 0600) // #nosec G306 G703
+	}
+
+	// Append to file
+	newContent := strings.TrimRight(existingStr, "\n") + "\n" + strings.TrimSpace(content) + "\n"
+	return os.WriteFile(absPath, []byte(newContent), 0600) // #nosec G306 G703
+}
+
+func getCopilotInstructions() string {
+	return `
+# efctl Context
+You are working on a project using 'efctl', the EVE Frontier CLI.
+Reference AGENTS.md for core principles.
+
+## efctl Commands
+- Init: efctl init
+- Up: efctl env up
+- Down: efctl env down
+- Status: efctl env status
+- Publish Extension: efctl env extension publish [contract-path]
+- Query World: efctl world query [object_id]
+`
+}
+
+func getClaudeInstructions() string {
+	return getCopilotInstructions()
+}
+
+func getGeminiInstructions() string {
+	return getCopilotInstructions()
+}