Default Workflow

[guettli]

Implement below plan.

[guettli]

Now I have enough context to write the updated plan.

Implementation Plan — Default Workflow (revised)

Change from the previous plan

The previous plan still wrote three stub files (plan.md, code.md, merge.md) containing default: <name> front-matter. Per the issue update, no prompt files are copied — even when the user wants the default flow. The defaults live entirely in the binary; loop/REPO-NAME/prompts/ stays empty unless the user explicitly chooses to customize.

1. Embed the default prompts as full files in the binary

New package internal/config/defaults/ with one .md per built-in prompt — full files (front-matter + body), not just bodies:

internal/config/defaults/plan.md
internal/config/defaults/code.md
internal/config/defaults/merge.md

Each is a normal prompt file, parsed by the same LoadPrompt as user files. Front-matter for each:

• plan.md: inputLabel: loop/plan, loop/plan-in-process, loop/plan-done, concurrency: 3.
• code.md: loop/code triple, concurrency: 1, routes: { merge: loop/merge }.
• merge.md: loop/merge triple, concurrency: 1, timeout: 2h, routes: { escalate: NeedSupervisor }.

Bodies are the current strings from init.go, copy-moved into these files (then deleted from init.go). The embed is the single source of truth.

A new helper internal/config/defaults.go:

//go:embed defaults/*.md
var defaultFS embed.FS

// DefaultNames is the closed set of built-ins, in deterministic load order.
var DefaultNames = []string{"plan", "code", "merge"}

// LoadDefaultPrompt parses one embedded prompt. Path is virtual ("<builtin>/plan.md")
// for error messages.
func LoadDefaultPrompt(name string) (*Prompt, error) { ... }

LoadPrompt is refactored: split its core into parsePrompt(name, virtualPath string, content []byte) so both the on-disk loader and the embed loader share validation.

2. LoadLoop merges built-ins with user overrides

In internal/config/loop.go:

• Load prompts/*.md as today, indexed by Prompt.Name.
• For each name in DefaultNames: if not present in the user set, parse the embedded default and append.
• Drop the "no prompts found" error (a loop with zero user files is now valid — the defaults populate it).
• Existing label-uniqueness and route-target validation runs after the merge, so a user file named plan.md cleanly replaces the built-in (its labels and routes are validated against the surviving set, including the other two built-ins).
• New Loop.Builtin map[string]bool (keyed by prompt name) lets downstream code (label-description renderer, tests, README hints) distinguish "this body lives in the binary" from "this body lives in prompts/".

Override semantics. Overrides are whole-file, by name: dropping prompts/code.md replaces all of the built-in code prompt (body, labels, concurrency, routes). There is no partial-override syntax; if the user only wants different labels with the default body, they write a stub file with default: code (see §3). Built-ins the user did not override stay in effect.

Opt-out. New optional config.yaml field:

defaultPrompts: false   # default true

When false, no built-ins are merged. The existing "at least one prompt" rule is re-enabled in that mode so an empty prompts/ directory is still a config error. Single switch, no per-prompt suppression — keeps the surface small.

3. default: front-matter (preserved from previous plan)

Still useful for the "I want default body, custom labels" case. In internal/config/prompt.go:

• Add Default string \yaml:"default"`tofrontMatter`.
• If fm.Default != "": look up LoadDefaultPrompt(fm.Default); unknown name → error; require the file's body to be empty (mixing is ambiguous → fail fast); fill p.Body from the default; fill Concurrency/Timeout/Routes only where the user's front-matter omitted them.
• A user file prompts/plan.md with default: plan and custom labels is the minimum customization for "default workflow under different label names".

Note the override is by file name, not by default:. prompts/myplan.md with default: plan adds a new prompt named myplan alongside the built-in plan (and triggers the label-uniqueness check if they share labels). To replace the built-in plan, the user names the file plan.md.

4. agentloop init writes no prompts at all

In init.go:

• Delete planPromptMD, codePromptMD, mergePromptMD, promptMD (all three bodies live in internal/config/defaults/*.md after §1).
• Still create prompts/ (empty) so the user has an obvious place to drop overrides.
• Still create config.yaml and acpx-config as today.
• Adjust the trailing fmt.Printf messages: tell the user the default plan/code/merge workflow is active out of the box and point at prompts/ as the customization hook plus a URL to the embedded defaults on the agentloop repo.

init_test.go:

• Replace the asserts that checked the generated files. After init, LoadLoop must succeed; the loaded Prompts slice must contain plan, code, merge; prompts/ on disk must be empty; Loop.Builtin["plan"] etc. must be true.
• Keep the Routes asserts (they now read from the embedded defaults, which is fine).

5. Label descriptions carry the in-tracker documentation

(Same as the previous plan, slightly retuned because there is no local file to point at for built-ins.)

internal/tracker/tracker.go:

• EnsureLabel(ctx, name) → EnsureLabel(ctx, name, description string). Implementation: Get → Create with description, or Update when description drifts. Per-backend MaxLabelDescriptionLen constant (GitHub 100, GitLab/Gitea/Forgejo ~2000); truncate with … see <url> suffix when the body does not fit.

internal/loop/loop.go ensureLabels:

• For each prompt, build descriptions and call EnsureLabel(name, desc).
• InputLabel (loop/plan): the full prompt body, followed by a footer:
  • For built-ins: \n---\nAdd this label to run the built-in "<name>" prompt. Override at loop/<repo>/prompts/<name>.md; source: <upstream-url>/internal/config/defaults/<name>.md.
  • For user prompts: \n---\nAdd this label to run the "<name>" prompt. Edit loop/<repo>/prompts/<name>.md to change these instructions.
• InProcessLabel (loop/plan-in-process): "An agent for loop/plan is currently running on this issue. On success → loop/plan-done."
• OutputLabel (loop/plan-done): "The loop/plan agent finished. Re-run by moving the issue back to loop/plan. Next step: loop/code." (the "Next step" line is added per declared route whose target is another prompt's InputLabel.)
• NeedSupervisor: a one-line MD list of every InputLabel in the loop.

<labels-url> derived from Config.RepoURL plus a per-backend labels path; helper lives in internal/tracker/links.go.

GitHub 100-char limit. Truncate to 97 chars and append … (defaults/<name>.md) for built-ins, … (prompts/<name>.md) for overrides. Document the limitation in the README. (Flagging it again as the one design trade-off — happy to drop the body entirely on GitHub if preferred.)

6. Tests

• internal/config/defaults_test.go: every name in DefaultNames parses cleanly via LoadDefaultPrompt; the resulting prompt has the expected labels, concurrency, routes.
• internal/config/loop_test.go:
  • Empty prompts/ + default config.yaml → loaded loop has the three built-ins; Builtin[name] true for each.
  • User file prompts/plan.md with a different body → built-in plan replaced (body matches the file); Builtin["plan"] false; code/merge still built-in.
  • defaultPrompts: false + empty prompts/ → load fails with the old "no prompts" error.
  • defaultPrompts: false + one user file → loads, only that prompt.
• internal/config/prompt_test.go: existing default: cases (unknown name, body-and-default conflict, partial override of concurrency/routes).
• init_test.go: see §4.
• internal/loop/loop_test.go: fake Tracker records descriptions passed to EnsureLabel; assert the built-in/user footer differ; assert OutputLabel description includes "Next step" lines derived from routes; assert NeedSupervisor lists every InputLabel.
• internal/tracker/links_test.go: URL helper per backend.

7. Documentation

• README "Structure" — prompts/ is shown as empty in the scaffold; add a sub-section "Default prompts" explaining that plan/code/merge run out of the box from the binary, and listing the override recipes (custom labels via default:, full replacement via same-name file, opt-out via defaultPrompts: false).
• README "How to create the labels in the forge?" — note that descriptions are kept in sync and what each holds.

Out of scope (intentionally not changing)

• No partial-override syntax beyond default:. Override granularity is whole-file by name.
• No per-prompt opt-out (only the global defaultPrompts: false).
• No template/include syntax inside prompt bodies.
• Built-in label names stay loop/plan etc. — renaming happens via override or default:.