tbdflow Skill

Overview

This skill enables an AI agent to manage a Trunk-Based Development (TBD) workflow using the

tbdflow

The skill exists to:

• Enforce short-lived branches
• Standardise commits
• Reduce Git decision-making
• Maintain a fast, safe path back to trunk (

  main

  )

tbdflow

When to Use

Use this skill when the user wants to:

• Start work on a task, ticket, or feature
• Commit staged changes
• Sync with trunk or check repository status
• Merge completed work back to

  main

• See what has changed since the last release

Typical trigger phrases include:

• “Start working on…”
• “Commit this”
• “Merge my work”
• “Sync me up”
• “What’s new?”

When Not to Use

Do not use this skill to:

• Create or manage long-lived branches
• Perform manual Git commands outside

  tbdflow

• Rewrite commit history
• Perform interactive rebases
• Merge without explicit user intent

If an action cannot be performed via

tbdflow

Instructions

Follow the instructions below exactly. Each capability defines intent, constraints, and decision rules.

1. Standardised Committing

Intent Create a structured, conventional commit on trunk or a short-lived branch.

Staging Behaviour

• tbdflow

  automatically stages the relevant changes when committing
• The agent must not run

  git add

  or any raw Git staging commands
• No explicit staging step is required from the user or the agent

Preconditions

• The working tree contains changes intended for commit
• No unresolved merge conflicts are present

Command

tbdflow commit -t <type> [-s <scope>] -m "<message>" [--issue <issue>] [-b]

Decision Rules

• Allowed commit types:

  • feat

    ,

    fix

    ,

    chore

    ,

    docs

    ,

    refactor

    ,

    test

    ,

    build

    ,

    ci

    ,

    perf

    ,

    revert

    ,

    style

• Never invent new commit types

• If no type is specified:

  • Default to

    chore

    unless behaviour changes

• DoD Checklist: If a

  .dod.yml

  file exists in the project root and

  --no-verify

  is not passed, an interactive checklist will appear. Unchecked items will result in a

  TODO:

  footer being appended to the commit message.

• Use

  -b

  /

  --breaking

  if the change introduces breaking behaviour

• Use

  --issue

  when the user references a ticket ID (JIRA, GitHub, etc.)

Use This When

• The user says “commit”, “save this”, or “check this in”
• The user describes completed work ready to be recorded

2. Creating Short-Lived Branches

Intent Start a new unit of work in a short-lived branch that will be merged back to trunk quickly.

Preconditions

• Working tree is clean or safely stashed
• The task is not exploratory or long-running

Command

tbdflow branch -t <type> -n <name> [--issue <issue>] [-f <from_commit>]

Decision Rules

• Branch naming follows:

  • <type>/<name>

    or

  • <type>/<issue>-<name>

• If the user provides a task description:

  • Slugify it for the

    -n

    parameter

• Use

  --issue

  when a ticket ID is available

• Use

  -f

  only if the user explicitly asks to branch from a non-HEAD commit

Use This When

• The user says “start working on…”
• A task requires isolation before merging to

  main

3. Workflow Completion & Integration

Intent Safely merge completed work back into trunk and clean up the branch.

Preconditions

• All intended commits are complete
• The branch is ready to be merged

Command

tbdflow complete -t <type> -n <name>

Decision Rules

• Infer

  <type>

  and

  <name>

  from:
  1. The current Git branch name
  2. Fallback: the most recent

     tbdflow branch

     invocation

• The merge is performed using

  --no-ff

• Both local and remote branch copies are deleted after merge

Use This When

• The user says “I’m done”, “merge my work”, or “ship this”

4. Syncing & Status

Intent Keep the local workspace aligned with trunk and provide situational awareness.

Commands

tbdflow sync
tbdflow status

Decision Rules

• Use

  sync

  to:
  • Pull and rebase from remote
  • Inspect recent history
  • Identify stale branches

• Use

  status

  to:
  • Show context-aware Git status, In monorepos, this excludes sub-project directories when at the root.
  • Handle monorepos correctly

Use This When

• The user says "sync", "catch me up", or "what's happening"
• Before committing, merging, or starting new work

Pre-Commit Workflow

Always run

tbdflow sync

tbdflow commit

The

sync

• Pulls and rebases from remote
• Shows current status (wraps

  git status

  )
• Ensures the workspace is aligned with trunk

This prevents conflicts and ensures commits are based on the latest trunk state.

Validation & Linting Behaviour

tbdflow

Commit Message Rules

Subject Line (

-m

message)

"add user profile"

"add feature"

"Add feature"

"fix bug"

"fix bug."

feat

fix

chore

docs

refactor

test

build

ci

perf

revert

style

feat

feature

-s login

-s "user login"

"add user profile"

""

-b

-b

Commit Body (Optional)

Issue Key (

--issue

)

PROJ-123

proj-123

Branch Name Rules

feat/

feature/

add-user-profile

Add User Profile

feat/API-456-add-user

Error Handling

If

tbdflow

1. Read the error message carefully
2. Correct the input based on the rules above
3. Retry with valid parameters
4. Do not fall back to raw Git commands

The agent should prefer generating valid inputs over relying on linter errors.

5. Changelog Generation

Intent Summarise changes using structured commit history.

Command

tbdflow changelog [--unreleased] [--from <ref>]

Decision Rules

• Use

  --unreleased

  when the user asks “What’s new?”
• Use

  --from <ref>

  when comparing against a specific tag or version

Use This When

• The user asks for release notes
• The user wants a summary of recent changes

Output Format

• Commands should be executed directly
• Explanations should be concise and factual
• Avoid narrating Git internals unless asked
• Prefer showing the command being run before or alongside results

Examples

tbdflow commit -t fix -s login -m "resolve timeout issue"

tbdflow branch -t feat -n add-user-profile --issue API-456

tbdflow complete -t <current_type> -n <current_name>

tbdflow sync

tbdflow changelog --unreleased

Notes

• Treat

  main

  (trunk) as sacred
• Prefer safety and clarity over cleverness
• Ask for clarification only when an action could be destructive