Practical Workflows

This page describes how Recalletta features combine in real-world engineering workflows. All examples use placeholder names. Some personal information has been redacted for security and ethical considerations.

The Multi-Day Refactor

Complex refactoring spans multiple days and dozens of sessions. Context drift is the biggest enemy — agents lose the "why" as soon as a session ends.

The Workflow

1. Pin the project so context injection is scoped correctly.

   recalletta pin my-project
   

2. Ask the agent to document the goal as a KB entry. Tell your agent: "Save the refactor goals to KB so future sessions remember them." The agent creates an important entry:

   recalletta kb set refactor/auth-v2 -t "Auth V2 Refactor Goals" -b "Migrating to JWT..." -i
   

   Marking it important (-i) means it is auto-injected into every new session's context.
3. Work and exit. On session end, the agent's work is captured automatically.
4. Resume next day. Start a new agent session. The agent sees the KB entry and yesterday's session summary in its context — no re-explaining needed.

Keep important entries compact. Every important entry consumes agent context window. Over-marking entries degrades agent performance.

The Crew Workflow (Multi-Agent)

This is the primary way to use Recalletta's crew system: you talk to the team lead, the team lead coordinates specialists.

The Workflow

1. Start a crew session. You work in a directory with a .crew/ marker. Your team lead (e.g., Atlas) is your main point of contact.

   recalletta crew summon atlas "We need to fix the checkout race condition"
   

2. The team lead coordinates. Atlas analyzes the problem, summons specialists, assigns tasks. You do not summon individual agents — the team lead does.
3. Agents communicate via the crew messaging system. They send reports to .crew/mail-board/, message each other with recalletta crew message, and coordinate through the team lead.
4. Observe any agent if you want to see their work:

   recalletta crew attach beacon
   

   On macOS, agent sessions open in terminal tabs automatically. On Linux, agents run in tmux sessions — use crew attach to connect.
5. Release the crew when work is done:

   recalletta crew release beacon
   recalletta crew release circuit
   

What You Do vs. What Agents Do

You (the user)	Agents
Talk to the team lead	Coordinate, assign tasks, summon other agents
Review results in mail-board	Write reports, send messages
Attach to observe progress	Execute tasks in their sessions
Release agents when done	Wait for instructions or self-coordinate

Automated Pipelines (Attractor)

The Attractor engine runs multi-stage workflows defined as DOT graph files.

The Workflow

1. Ask an agent to create the pipeline. The agent uses the Attractor SPEC.md to write a .dot file defining the stages, personas, and flow.
2. Run the pipeline:

   recalletta attractor run review.dot --backend crew
   

3. Review results in .crew/mail-board/ where each stage writes its report.

DOT pipeline files are complex — when you need one, ask an agent to generate it from your high-level description.

Onboarding a New Project

When starting work on a new codebase, Recalletta accelerates the ramp-up.

The Workflow

1. Set up Recalletta (one-time):

   recalletta register
   recalletta login
   recalletta init
   

   This installs hooks for all detected agent clients (Claude Code, Gemini CLI, Codex CLI).
2. Start your agent client (e.g., Claude Code). The hooks activate automatically — sessions are captured, context is injected.
3. Ask the agent to build a KB as you explore. "Save the architecture decisions we discussed to KB." Over time, the KB becomes the project's institutional memory.
4. Future sessions get the KB entries and past session context automatically. No manual steps needed.