Workflows & Examples

Practical patterns for everyday development.

Set Up Project Context

Ensure AdaL understands your codebase by creating an AGENTS.md file:

/init

This generates a project-specific AGENTS.md with:

• Repository structure and key files
• Build commands and workflows
• Coding conventions and patterns
• Important context for better assistance

Tip: Review and customize the generated file for your team's needs.

Explore Codebase

Analyze this codebase and give me an architecture overview

Where is the authentication logic implemented?

@src/auth/service.ts Explain how this works

Debug Issues

I'm getting: TypeError: Cannot read property 'map' of undefined at UserList.tsx:42

AdaL analyzes, proposes fixes, implements with tests.

Run the tests to verify the fix

Refactor Code

Basic:

Refactor this function to be more readable

Convert callbacks to async/await

Apply the repository pattern to data access

Large-scale (use safety pattern):

Create a git branch called refactor/auth-service

Now refactor the auth system step by step, running tests after each change

Generate & Analyze Images

Generate an image of a futuristic city at sunset

Create 4 variants of a logo design for a coffee shop

Read this screenshot and explain the layout issue

AdaL generates images using Google Gemini models. Use n for multiple variants from the same prompt. See Image Generation & Analysis for details.

Web Search

What are best practices for JWT authentication in Express.js?

Search for common React performance issues

What's the latest version of Next.js?

Research PostgreSQL indexing best practices

Work with Tests

Generate unit tests for @src/services/userService.ts

Create integration tests for /api/auth endpoints

Write failing tests for shopping cart, then implement it

Generate Documentation

Generate OpenAPI docs for all REST endpoints

Add JSDoc comments to @src/services/userService.ts

Update README with the new authentication setup

Create PRs

Show me what changed in this branch

Create a pull request description for these changes

Create a meaningful commit message and push to origin

Reference Files with @

@src/server.ts Add error handling middleware

@src/auth/service.ts @src/auth/middleware.ts Ensure consistent error handling

@src/services/ Add logging to all service methods

Use @ when targeting specific files. Skip @ when creating new files or searching.

Thinking Mode

Extended reasoning for complex tasks. Powerful but token-intensive.

Enable on-demand:

• Keywords: "think hard", "think deeply", "reason carefully"

  > debug this auth error, think hard

• Tab shortcut: Toggle mid-task. Takes effect at the next step — no need to cancel your query.

Tip: Reserve for complex debugging, architecture decisions, or when initial responses miss the mark.

Manage Work Sessions

Keep your session focused and clean:

/clear      # Clear context and start fresh
/compact    # Summarize and reduce context (keep working)
/resume     # Resume previous session
/quit       # Exit (or Ctrl+C)

Auto-compact: AdaL automatically compacts when context grows large, preserving key information while freeing space.

When to use:

• /clear — Switching to unrelated task
• /compact — Long session getting slow, want to continue same work

Work on Multiple Branches

To work on unrelated changes at the same time, ask AdaL to use a worktree — an isolated checkout on its own branch, so two pieces of work never touch the same files:

> the retry bug and the auth refactor are unrelated — work on both at once

AdaL creates a worktree per task, works inside it, and tells you where each one is. In Engineer mode it puts a worker in each and merges the results back.

Worktrees live in .agents/worktrees/<name>/ on branch worktree-<name>, and AdaL copies your gitignored setup files into each new one so it is ready to run. Control what gets copied with .agents/worktrees.toml in your project root:

[copy]
include = [".env", ".env.*", "config/secrets.json"]

Add .agents/worktrees/ to your .gitignore so worktree contents do not show up as untracked files in your main checkout. Keep .agents/worktrees.toml committed — which files a fresh checkout needs is a property of the project, not of your machine.

Ask AdaL to clean up when you are done, and it removes the worktrees whose work has landed. It will not remove one holding uncommitted changes or unpushed commits unless you tell it to.

Managing worktrees yourself

AdaL does not wrap git here. If you want to create or remove a worktree by hand, use git directly:

git worktree add .agents/worktrees/feature-auth -b worktree-feature-auth
cd .agents/worktrees/feature-auth && adal

git worktree list
git worktree remove .agents/worktrees/feature-auth

Running adal inside a worktree works exactly like running it anywhere else — a worktree is just a directory.

Quick Reference

Task	How to Ask AdaL
Generate image	"Generate an image of a sunset over mountains"
Multiple variants	"Generate 4 variants of a logo design"
Analyze image	"Read this screenshot and tell me what's wrong"
Web search	"Search for React best practices"
Read file	"@src/utils/helper.ts summarize this"
Edit file	"@src/app.py fix the bug at line 42"
Run tests	"Run pytest for the auth module"
Debug error	"I'm getting TypeError at line X"

Common Slash Commands

/help         # Show available commands
/clear        # Clear context and start fresh
/compact      # Summarize and reduce context
/resume       # Resume previous session
/stats        # Show session info
/quit         # Exit

Best Practices

Prompts:

• ✅ "Create a React component for user profiles with avatar, name, email, and bio fields"
• ❌ "Make a user component"

Security:

• No API keys in prompts
• Use environment variables
• Review generated code