beads/cmd/bd/onboard.go
Harry e64dee561e feat(init): add --agents-file flag to customize agent instructions filename
Add --agents-file flag to bd init allowing users to specify a custom
filename for agent instructions (default remains AGENTS.md). This
addresses the use case where projects prefer different naming
conventions (e.g. BEADS.md) without requiring a post-init rename.

Changes:
- Add config.AgentsFile() accessor and config.ValidateAgentsFile()
  with security validation (path traversal, symlinks, extension check)
- Add --agents-file flag to bd init with config persistence
- Thread configured filename through init_agent.go
- Update setup/agents.go to use config.AgentsFile()
- Update doctor checks to search configured filename
- Update onboard messaging to reference configured filename
- Add DefaultAgentsFile constant for consistent fallback

The filename is persisted to .beads/config.yaml under agents.file
and read by all subsystems via config.AgentsFile().

Fixes #2737

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-03-22 11:17:43 -07:00

136 lines
4.1 KiB
Go

package main
import (
"fmt"
"io"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/ui"
)
const copilotInstructionsContent = `# GitHub Copilot Instructions
## Issue Tracking
This project uses **bd (beads)** for issue tracking.
Run ` + "`bd prime`" + ` for workflow context, or install hooks (` + "`bd hooks install`" + `) for auto-injection.
**Quick reference:**
- ` + "`bd ready`" + ` - Find unblocked work
- ` + "`bd create \"Title\" --type task --priority 2`" + ` - Create issue
- ` + "`bd close <id>`" + ` - Complete work
- ` + "`bd dolt push`" + ` - Push beads to remote
For full workflow details: ` + "`bd prime`" + ``
const agentsContent = `## Issue Tracking
This project uses **bd (beads)** for issue tracking.
Run ` + "`bd prime`" + ` for workflow context, or install hooks (` + "`bd hooks install`" + `) for auto-injection.
**Quick reference:**
- ` + "`bd ready`" + ` - Find unblocked work
- ` + "`bd create \"Title\" --type task --priority 2`" + ` - Create issue
- ` + "`bd close <id>`" + ` - Complete work
- ` + "`bd dolt push`" + ` - Push beads to remote
For full workflow details: ` + "`bd prime`" + ``
func renderOnboardInstructions(w io.Writer) error {
writef := func(format string, args ...interface{}) error {
_, err := fmt.Fprintf(w, format, args...)
return err
}
writeln := func(text string) error {
_, err := fmt.Fprintln(w, text)
return err
}
writeBlank := func() error {
_, err := fmt.Fprintln(w)
return err
}
if err := writef("\n%s\n\n", ui.RenderBold("bd Onboarding")); err != nil {
return err
}
agentsFile := config.AgentsFile()
if err := writeln("Add this minimal snippet to " + agentsFile + " (or create it):"); err != nil {
return err
}
if err := writeBlank(); err != nil {
return err
}
if err := writef("%s\n", ui.RenderAccent("--- BEGIN AGENTS.MD CONTENT ---")); err != nil {
return err
}
if err := writeln(agentsContent); err != nil {
return err
}
if err := writef("%s\n\n", ui.RenderAccent("--- END AGENTS.MD CONTENT ---")); err != nil {
return err
}
if err := writef("%s\n", ui.RenderBold("For GitHub Copilot users:")); err != nil {
return err
}
if err := writeln("Add the same content to .github/copilot-instructions.md"); err != nil {
return err
}
if err := writeBlank(); err != nil {
return err
}
if err := writef("%s\n", ui.RenderBold("How it works:")); err != nil {
return err
}
if err := writef(" • %s provides dynamic workflow context (~80 lines)\n", ui.RenderAccent("bd prime")); err != nil {
return err
}
if err := writef(" • %s auto-injects bd prime at session start\n", ui.RenderAccent("bd hooks install")); err != nil {
return err
}
if err := writeln(" • " + agentsFile + " only needs this minimal pointer, not full instructions"); err != nil {
return err
}
if err := writeBlank(); err != nil {
return err
}
if err := writef("%s\n\n", ui.RenderPass("This keeps "+agentsFile+" lean while bd prime provides up-to-date workflow details.")); err != nil {
return err
}
return nil
}
var onboardCmd = &cobra.Command{
Use: "onboard",
GroupID: "setup",
Short: "Display minimal snippet for agent instructions file",
Long: `Display a minimal snippet to add to your agent instructions file for bd integration.
By default, the agent instructions file is AGENTS.md. Use 'bd init --agents-file'
to configure a different filename (e.g. BEADS.md).
This outputs a small (~10 line) snippet that points to 'bd prime' for full
workflow context. This is the same minimal profile that 'bd init' generates
by default. This approach:
• Keeps your agent file lean (doesn't bloat with instructions)
• bd prime provides dynamic, always-current workflow details
• Hooks auto-inject bd prime at session start
For agents that don't support hooks (Codex, Factory, etc.), use
'bd init --agents-profile=full' to embed the complete command reference.`,
Run: func(cmd *cobra.Command, args []string) {
if err := renderOnboardInstructions(cmd.OutOrStdout()); err != nil {
_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Error: %v\n", err)
}
},
}
func init() {
rootCmd.AddCommand(onboardCmd)
}