The Big Feature: Search

Search is why Freddy exists — it's in the first line of SPEC.md. It's also the biggest feature so far, and this chapter is about not supervising it: a swarm pipeline builds the whole thing in an isolated git worktree while your working tree stays untouched.

The problem

Search touches everything at once: a controller, the FTS5 foundation from Chapter 5, a brand-new Search page, ranking, snippet highlighting, empty states. That's a plan, a build, tests, a review, and fixes — too big for one supervised sitting. You'd be watching diffs scroll by for half an hour, approving edits faster than you can actually read them.

The hard way

One giant prompt, one long turn. The agent works in your working tree for twenty minutes. You don't dare touch anything meanwhile — not even a quick typo fix — because every file is potentially mid-edit. And if stage 3 of the work goes sideways, stages 1 and 2 are already tangled into your tree, and untangling a half-landed feature by hand is worse than writing it yourself.

The Elyra way: swarm pipelines

Install the extension:

/ext

Select @elyracode/swarm, then /reload. See what it offers:

/swarm

  Available pipelines:
  build     plan -> code -> test -> review -> fix
  review    multi-perspective review of changes
  refactor  analyze -> plan -> transform -> verify

A pipeline is a chain of stages, each run by its own sub-agent, each stage's output feeding the next. For search, build is the one we want — and one flag makes it safe to walk away from. First, commit anything outstanding (you'll see why in a moment), then:

/swarm --worktrees build implement full-text search per SPEC.md
  using the existing notes_fts table: SearchController, /search
  Inertia page, snippet highlighting, ranked by bm25

Same prompt discipline as ever — scope ("per SPEC.md", "the existing notes_fts table") and concrete deliverables. The pipeline picks it up from there.

Worktree mode, precisely

--worktrees is worth understanding exactly, because it changes the risk calculus of big autonomous work:

• Every stage runs as its own isolated elyra -p sub-agent inside a detached git worktree based on HEAD. Your working tree is never touched while the pipeline runs — keep editing, keep browsing freddy.test, nothing collides.
• Read-only stages (plan, review) are mechanically restricted to read, grep, find, and ls tools — not just prompted to behave. A planner cannot edit, period.
• Stage outputs chain: the plan feeds the coder, the test results feed the reviewer, the review feeds the fix stage.
• When all stages finish, the combined changes are checked for conflicts against files that changed in your tree during the run. Clean → applied to your working tree uncommitted, for your review — Elyra never commits unbidden. Conflict or failure → nothing is applied, the worktree is kept, and recovery instructions are printed.
• Outside a git repo, it degrades to the classic inline mode.

While it runs, the pipeline reports stage by stage:

  [Planning] -> [Coding] -> [Testing] -> [Reviewing] -> [Fixing]

  Planning   done  (search plan: controller, route, page,
                    bm25 ranking, snippet() for highlights)
  Coding     done  (5 files changed)
  Testing    done  (composer test: 2 failures)
  Reviewing  done  (1 warning: empty-query handling)
  Fixing     done  (failures + warning resolved, tests green)

Note the shape: the pipeline caught its own test failures and its own review warning, and fixed both — the Chapter 7 and Chapter 8 loops, chained, without you in the middle. Then:

  All 5 stages completed in an isolated git worktree.
  Applied 6 changed file(s) to your working tree (uncommitted,
  ready for review):

  app/Http/Controllers/SearchController.php
  routes/web.php
  resources/js/pages/Search.svelte
  resources/js/components/SearchResult.svelte
  tests/Feature/SearchTest.php
  SPEC.md (V1 checklist: search marked done)

Reviewing the result

Everything is sitting in your tree, uncommitted. This is the payoff of the whole model: instead of supervising every edit as it happened, you review one finished diff at your own pace:

git diff

(or /diff inside Elyra). The controller queries notes_fts with ORDER BY bm25(notes_fts), the Svelte page uses runes as AGENTS.md demands, snippets highlight the matched terms, and the empty state has actual copy instead of a blank div. Open https://freddy.test/search, type "elyra", watch ranked results come back. Then, and only then:

> Commit as "feat: full-text search (FTS5 + bm25 ranking)"

The feature everything since Chapter 5 has been pointing at — shipped in one pipeline run, reviewed as one diff.

What you learned

• Big features want isolated pipelines. plan → code → test → review → fix, each stage its own sub-agent, outputs chained.
• You review a finished diff, not a stream of live edits. Judgment at the end beats reflexive approval in the middle.
• Commit before swarming. Sub-agents start from HEAD; uncommitted work is invisible to them.
• Worktree mode is autonomy without collateral. Your tree stays untouched during the run; results apply uncommitted only when clean, and failures leave nothing behind but the worktree and instructions.