Readme

Tofie Dev Flow Automation #

Tofie is BonsAI’s automated development workflow system that connects Linear, n8n, GitHub, and Claude Code to streamline the software development lifecycle from planning to pull request submission.

Overview #

Tofie automates the entire development workflow by orchestrating multiple services:

  • Linear - Project management and issue tracking
  • n8n - Cloud automation and webhook orchestration
  • GitHub - Code repository and pull request management
  • Claude Code - AI-powered code generation and planning
  • Coder Instance - EC2-based development environment with git worktrees

Quick Start #

For Team Members #

  1. Create or find a Linear issue you want to work on

  2. Mention Tofie in a comment with your request:

    @Tofie plan this issue

  3. Wait for Tofie to respond - It will update the Linear issue status and add comments when complete

  4. Review the generated plan in the Linear issue comments

  5. Trigger implementation when ready:

    @Tofie implement this

  6. Review the draft PR created by Tofie on GitHub

What Tofie Can Do #

Command Description Linear Status Transition
@Tofie plan Generate comprehensive implementation plan Todo → Planning → Planned
@Tofie implement Execute the plan and create code changes Planned → In Progress → In Review
@Tofie review Perform code review on changes Any → Under Review
@Tofie pr Submit pull request to GitHub Any → PR Created

Architecture # 

graph TB
    A[Linear Issue] -->|Webhook| B[n8n Automation]
    B -->|SSH| C[Coder Instance]
    C -->|Claude CLI| D[Claude Code]
    D -->|Git Worktree| E[Isolated Branch]
    E -->|Plan/Code| F[PLAN.md + Changes]
    F -->|gh CLI| G[GitHub Draft PR]
    G -->|Update| A

    style A fill:#5e6ad2
    style B fill:#ff6c5c
    style D fill:#cc9b7a
    style G fill:#238636

System Components #

  1. Linear - Source of truth for issues and project management

    • Issues contain requirements, comments, and acceptance criteria
    • Webhooks notify n8n of comment mentions
    • Status updates track workflow progress

  2. n8n - Automation orchestrator

    • Listens for Linear webhooks
    • Parses Tofie commands from comments
    • Executes Tofie scripts via SSH
    • Updates Linear with results

  3. Coder Instance - Development environment

    • EC2 instance with main repository
    • Git worktrees for isolated work
    • Claude Code CLI installed
    • All Tofie scripts and configurations

  4. Claude Code - AI development assistant

    • Generates implementation plans
    • Writes code changes
    • Reviews code quality
    • Creates PR descriptions

  5. GitHub - Code hosting and collaboration

    • Receives pull requests from Tofie
    • All PRs created as drafts
    • Links back to Linear issues

Key Features #

Automated Planning #

  • Comprehensive implementation plans using Context Engineering framework
  • Analysis of Linear issue comments and requirements
  • Risk assessment and success criteria
  • Stored in .plans/PLAN.md with Linear collapsible sections

Isolated Development #

  • Each issue gets its own git worktree
  • No interference with main branch or other work
  • Clean separation of concerns

AI-Powered Implementation #

  • Claude Code generates code following project patterns
  • Respects existing architecture and conventions
  • Runs quality checks (lint, format, tests)
  • Creates conventional commit messages

Draft Pull Requests #

  • All PRs created as drafts for review
  • Generated PR descriptions reference the plan
  • Links to Linear issue automatically
  • Includes implementation summary and testing notes

Workflow Stages #

1. Planning Stage #

Trigger: User comments @Tofie plan in Linear issue

What Happens:

  1. Linear status → Planning
  2. n8n receives webhook
  3. Creates git worktree from main branch
  4. Generates linear-metadata.json with full issue context
  5. Claude creates comprehensive PLAN.md
  6. Plan posted to Linear issue comments
  7. Linear status → Planned

Output: .plans/PLAN.md with implementation roadmap

2. Implementation Stage #

Trigger: User comments @Tofie implement in Linear issue

What Happens:

  1. Linear status → In Progress
  2. Reads PLAN.md from planning stage
  3. Claude implements changes following the plan
  4. Runs mise fix && mise ci for quality checks
  5. Creates conventional commits
  6. Linear status → In Review

Output: Code changes committed to feature branch

3. PR Submission Stage #

Trigger: User comments @Tofie pr or automatic after implementation

What Happens:

  1. Reviews all commits on the branch
  2. Generates PR title (conventional commit format)
  3. Creates PR description referencing plan
  4. Submits draft PR to GitHub
  5. PR URL posted to Linear issue
  6. Linear status → PR Created

Output: Draft PR on GitHub

Metadata Files #

Tofie creates metadata files in .plans/ directory (gitignored):

linear-metadata.json # 

{
  "branchName": "john/eng-1144-feat-add-filtering",
  "issueIdentifier": "ENG-1144",
  "agentSessionId": "session-abc-123",
  "project": {
    "id": "proj-123",
    "name": "BonsAI Core",
    "key": "ENG"
  },
  "issue": {
    "id": "issue-456",
    "identifier": "ENG-1144",
    "title": "Add date range filtering to invoice list",
    "description": "Full issue description...",
    "comments": [...]
  },
  "createdAt": "2025-11-03T10:00:00Z",
  "updatedAt": "2025-11-03T10:00:00Z"
}

n8n-metadata.json # 

{
  "event_server_url": "https://sample.app.n8n.cloud/webhook/tofie",
  "signing_key": "your-actual-key-here",
  "createdAt": "2025-11-03T10:00:00Z"
}

pr-info.json # 

{
  "prNumber": 123,
  "prUrl": "https://github.com/globalbpo-ai/bonsai/pull/123",
  "prTitle": "feat(webapp): add date range filtering to invoice list",
  "createdAt": "2025-11-03T12:00:00Z"
}

Git Worktree Structure #

Tofie uses git worktrees for isolated development:

/home/coder/
├── bonsai/                    # Main repository
│   └── tools/local/scripts/tofie/  # Tofie scripts
└── trees/                     # Worktrees directory
    ├── john-eng-1144/         # Worktree for ENG-1144
    │   ├── .plans/            # Gitignored planning artifacts
    │   │   ├── PLAN.md        # Implementation plan
    │   │   ├── linear-metadata.json
    │   │   ├── n8n-metadata.json
    │   │   └── pr-info.json
    │   └── [source code...]
    └── jane-eng-2205/         # Another parallel worktree
        ├── .plans/
        └── [source code...]

Security & Authentication #

SSH Access #

  • n8n connects to Coder instance via SSH
  • Uses SSH key authentication
  • Limited to executing Tofie scripts only

GitHub Token #

  • Stored in Doppler secrets management
  • Retrieved via doppler secrets get GITHUB_TOKEN
  • Required for PR creation via gh CLI

Linear API #

  • Webhook verification using signing keys
  • API tokens for status updates and comments
  • Stored securely in n8n credentials

Error Handling #

Script Failures #

  • All scripts return JSON output with success status
  • Errors logged to stderr (captured by n8n)
  • Linear issue updated with error status
  • n8n can retry failed operations

Timeout Handling #

  • Planning: 30 minute timeout
  • Implementation: 60 minute timeout
  • PR submission: 10 minute timeout
  • Long operations run in background on Coder instance

Recovery #

  • Worktrees can be reused if they exist
  • Scripts detect existing branches
  • Can resume from any stage
  • Manual intervention possible via Coder instance

Best Practices #

For Users #

  1. Write clear issue descriptions - Better input = better output
  2. Provide acceptance criteria - Helps Tofie understand success
  3. Add comments with context - Tofie analyzes all comments
  4. Review plans before implementation - Catch issues early
  5. Test draft PRs thoroughly - Tofie creates drafts for your review

For Maintainers #

  1. Keep scripts idempotent - Safe to run multiple times
  2. Use JSON for input/output - Structured data for n8n
  3. Log to stderr, output to stdout - Clean separation
  4. Update Linear status transitions - Keep users informed
  5. Handle edge cases gracefully - Existing branches, missing files, etc.

Common Issues & Solutions #

“Worktree already exists” #

  • Tofie will reuse existing worktree
  • To start fresh: manually remove worktree first
  • Check: git worktree list on Coder instance

“PR already exists for branch” #

  • submit-pr.sh detects existing PRs
  • Returns existing PR info without creating duplicate
  • Safe to run multiple times

“PLAN.md not found” #

  • Planning stage may have failed
  • Check Linear issue for error messages
  • Can manually run planning script

“Claude CLI permission issues” #

  • Scripts use --dangerously-skip-permissions for subagents
  • Required for automated file writes
  • Safe in isolated worktree environment

Documentation #

Support #

For questions or issues:

  1. Check Troubleshooting Guide
  2. Review Examples for common scenarios
  3. Ask in #tofie-support Slack channel
  4. Contact DevOps team for infrastructure issues

Version History #

  • v1.0 (2025-11-03) - Initial release with planning and implementation
  • v1.1 (2025-11-03) - Added Linear collapsible sections support
  • v1.2 (2025-11-03) - Draft PR creation, existence checking