Skip to content

feat: add btw_task() for running pre-formatted task files#169

Merged
gadenbuie merged 7 commits intomainfrom
feat/btw-task
Feb 25, 2026
Merged

feat: add btw_task() for running pre-formatted task files#169
gadenbuie merged 7 commits intomainfrom
feat/btw-task

Conversation

@gadenbuie
Copy link
Collaborator

Summary

This PR adds btw_task(), a new function for running pre-formatted task files with YAML frontmatter configuration and markdown body content. Task files use the same format as btw.md files but describe specific workflows that can be executed interactively or as tools.

Key features:

  • Template interpolation: Named arguments become template variables using {{ variable }} syntax
  • Additional context: Unnamed arguments are converted to text via btw() and appended to the system prompt
  • Multiple execution modes: Interactive app (default), console chat, or return as ellmer tool/client
  • Flexible configuration: Task files define their own client, model, and tool configuration
  • Tool metadata: Task files can specify name, title, description, and icon for tool mode

The implementation includes:

  • Core btw_task() function (251 lines) with comprehensive documentation
  • Test suite with 225 lines of coverage including template interpolation and context handling
  • Three example task files: analyze-package.md, code-review.md, data-summary.md
  • README in inst/tasks/ explaining the task file format

This establishes the foundation for user-defined task workflows that can be shared, versioned, and invoked both interactively and programmatically.

Verification

Create a simple task file and run it:

# Create a task file
tmp <- tempfile(fileext = ".md")
cat(file = tmp, '---
client: anthropic/claude-sonnet-4-6
tools: [docs]
---

Summarize the {{ pkg }} package in one sentence.
')

# Run with template interpolation
btw_task(tmp, pkg = "dplyr", mode = "tool")

# Or with additional context
btw_task(tmp, pkg = "ggplot2", mtcars, mode = "client")

- Add test for unnamed args as additional context (previously untested
  despite being a documented feature)
- Delete the skipped conditional-sections test, which covered no
  assertions and signalled an abandoned attempt rather than a known gap
- Wrap the example-files test in a describe() block for consistency with
  the rest of the file
…data

System prompt:
- Replace the system prompt with the task-specific content rather than
  appending to btw's standard session/tool/project prompts, matching the
  pattern used by btw_task_create_readme() and btw_task_create_btw_md()

Context args:
- Switch from do.call(btw, ...) to enquos() + eval_tidy() + btw_this(),
  which preserves the original expressions so btw can derive object names
  (do.call passed evaluated values, losing the expression context that
  btw()'s NSE relies on)

Tool metadata from YAML frontmatter:
- Read optional name, title, description, icon fields from task file YAML
- Derive tool name from name field or file basename (hyphens → underscores)
- Derive display name from title field or title-cased name
- Add ellmer::tool_annotations() with title/read_only_hint/open_world_hint
- Apply custom_icon() when icon field is present in YAML, matching the
  btw_agent_tool() pattern

Minor cleanup:
- Remove redundant comments that restate what the next line does
- Compute display_name once before mode dispatch instead of recomputing
  task_name separately inside the console and app branches
- Derive tool description from description YAML field when present,
  otherwise take the first non-empty line of the task body (stripping
  markdown header markers) rather than blindly substr()-ing at 100 chars
@gadenbuie gadenbuie changed the title feat: add btw_task() for running pre-formatted task files feat: add btw_task() for running pre-formatted task files Feb 23, 2026
@gadenbuie gadenbuie marked this pull request as ready for review February 23, 2026 18:47
The bundled example task files weren't ready to ship. Deleted
inst/tasks/ entirely and replaced the test coverage with a minimal
fixture at tests/testthat/fixtures/test-analyze-package.md.
@gadenbuie gadenbuie merged commit 5900639 into main Feb 25, 2026
9 checks passed
@gadenbuie gadenbuie deleted the feat/btw-task branch February 25, 2026 21:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant