{"id":44871376,"url":"https://github.com/cladam/tbdflow","last_synced_at":"2026-04-11T22:17:18.137Z","repository":{"id":304005182,"uuid":"1014684893","full_name":"cladam/tbdflow","owner":"cladam","description":"tbdflow is a command-line tool designed to streamline and safeguard your Git workflow for Trunk-Based Development.","archived":false,"fork":false,"pushed_at":"2026-04-11T14:07:16.000Z","size":20683,"stargazers_count":44,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-11T14:12:13.188Z","etag":null,"topics":["cli","continuous-delivery","continuous-integration","conventional-commits","devops","fix-forward","flow","git","tbd","trunk","trunk-based-development","workflow"],"latest_commit_sha":null,"homepage":"https://cladam.github.io/projects/tbdflow/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cladam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"custom":["https://paypal.me/ClaesAdamsson"]}},"created_at":"2025-07-06T07:52:25.000Z","updated_at":"2026-04-11T14:07:21.000Z","dependencies_parsed_at":"2025-07-10T22:01:15.813Z","dependency_job_id":"77500af4-21f5-446b-a5e1-f33ecb4b6a30","html_url":"https://github.com/cladam/tbdflow","commit_stats":null,"previous_names":["cladam/tbdflow"],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/cladam/tbdflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cladam%2Ftbdflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cladam%2Ftbdflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cladam%2Ftbdflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cladam%2Ftbdflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cladam","download_url":"https://codeload.github.com/cladam/tbdflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cladam%2Ftbdflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31697355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T21:17:31.016Z","status":"ssl_error","status_checked_at":"2026-04-11T21:17:24.556Z","response_time":54,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","continuous-delivery","continuous-integration","conventional-commits","devops","fix-forward","flow","git","tbd","trunk","trunk-based-development","workflow"],"created_at":"2026-02-17T13:05:12.007Z","updated_at":"2026-04-11T22:17:18.127Z","avatar_url":"https://github.com/cladam.png","language":"Rust","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/tbdflow-logo.png\" alt=\"tbdflow logo\" width=\"200\"/\u003e\n  \u003c/p\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003ci\u003e\u003cb\u003eKeep your code flowing\u003c/b\u003e\u003c/i\u003e\u003cbr/\u003e\n  \u003c/p\u003e\n\n[![Crates.io](https://img.shields.io/crates/v/tbdflow.svg)](https://crates.io/crates/tbdflow)\n[![Downloads](https://img.shields.io/crates/d/tbdflow.svg)](https://crates.io/crates/tbdflow)\n\n\u003c/div\u003e\n\n## The problem\n\nMany teams say they practise Trunk-Based Development but in day-to-day reality things deviate:\n\n- **Commit messages become inconsistent.** Everyone formats them a little differently.\n- **Branches that were meant to live for hours** stick around for days.\n- **Merging back to main** turns into a manual sequence people half-remember.\n- **Two people change the same file** and nobody notices until a push fails.\n- **The Definition of Done exists,** but it lives in a document no one looks at during the work.\n\nNone of this breaks the build immediately. But over time, the trunk stops feeling safe to work in.\n\n## The solution\n\n`tbdflow` is a small CLI that **codifies your team's Trunk-Based workflow** so the safe path is always the easiest path.\n\n```bash\ncargo install tbdflow\n```\n\nIt handles the ceremony (pulling, rebasing, linting, pushing) so you can stay focused on the work.\n\n![A terminal running the command tbdflow](docs/commit-demo.gif \"A demo of tbdflow running commit-to-main commands\")\n\n## What it does\n\n| Pain point                     | How tbdflow helps                                                          |\n|--------------------------------|----------------------------------------------------------------------------|\n| Inconsistent commits           | `tbdflow commit` enforces Conventional Commits with built-in linting       |\n| Long-lived branches            | `tbdflow branch` + `tbdflow complete` with stale-branch warnings           |\n| \"Did I pull before pushing?\"   | `tbdflow sync` + auto-rebase before every commit to main                   |\n| Pulling a broken trunk         | `tbdflow sync` pre-flight CI check warns before pulling a red build        |\n| Merge conflicts you didn't see | `tbdflow radar` shows who else is touching the same files, before you push |\n| \"Why was this done?\"           | `tbdflow task` + `tbdflow note` captures intent before it's lost           |\n\n## Philosophy\n\n* **Main is where the work happens.** `tbdflow commit` is your daily driver: pull, commit, push, done. Small and\n  frequent beats large and delayed.\n* **Branches are short-lived guests.** They're supported, but they should check out quickly.\n* **Cleanup shouldn't be your job.** Completed branches get merged, tagged (for releases), and deleted automatically.\n* **Commit messages should tell a story.** [Conventional Commits](https://www.conventionalcommits.org/) keep the\n  history readable for humans and machines alike.\n* **Collaboration should be visible.** `tbdflow radar` shows who else is touching the same files, turning silent\n  conflicts into early conversations.\n\n### Why not just use Git?\n\nYou absolutely should. `tbdflow` isn't a replacement. You'll still reach for raw `git` when rebasing, cherry-picking,\nor bisecting.\n\nThink of it as a **workflow assistant** that wraps the repeatable parts of your day:\n\n1. **Everyone does it the same way.**\n   Commits, branches, and releases follow the same steps every time. No more \"how did you format that commit again?\"\n\n2. **Less to keep in your head.**\n   You don't need to remember `pull --rebase` then commit then push then tag then delete branch. The CLI does.\n\n3. **The TBD path is the easy path.**\n   For 80% of your day, `tbdflow` keeps you in the flow. For the other 20%, Git is right there.\n\n### Installation\n\nYou need [Rust and Cargo](https://www.rust-lang.org/tools/install) installed.\n\n#### Installing from crates.io\n\n```bash\ncargo install tbdflow\n```\n\nTo update to the latest version:\n\n```bash\ntbdflow update\n```\n\n#### Building from source\n\nOr build it yourself:\n\n```bash\ngit clone https://github.com/cladam/tbdflow.git\ncd tbdflow\nsudo cargo install --path . --root /usr/local\n```\n\n### Monorepo Support\n\nIf you work in a monorepo, `tbdflow` understands that not every commit should touch every directory.\n\nWhen you run `tbdflow commit`, `tbdflow sync` or `tbdflow status` from the repo root, only root-level files are\naffected. Project subdirectories are left alone. Run the same commands from inside a project directory and they\nautomatically scope to that directory. (Run `tbdflow init` in each subdirectory to set this up.)\n\nThis is configured in your root `.tbdflow.yml` file:\n\n```\n# in .tbdflow.yml\nmonorepo:\nenabled: true\n  # A list of all directories that are self-contained projects.\n  # These will be excluded from root-level commits and status checks.\n  project_dirs:\n    - \"frontend\"\n    - \"backend-api\"\n    - \"infra\"\n```\n\nFor an overview and to inspect your current configuration, you can run `tbdflow info`.\n\n#### Handling Cross-Cutting Changes\n\nFor \"vertical slice\" changes that intentionally touch multiple project directories, you can use the `--include-projects`\nflag.\nThis flag overrides the default safety mechanism and stages all changes from all directories, allowing you to create a\nsingle, cross-cutting commit.\n\n### Interactive Wizard Mode\n\nTo make `tbdflow` even more user-friendly, the core commands (`branch`, `commit`, `complete`, `changelog`) now feature\nan interactive \"wizard\" mode.\n\nIf you run one of these commands without providing the required flags, `tbdflow` will automatically launch a\nstep-by-step guide.\nThis is perfect for new users who are still learning the workflow, or for complex commits where you want to be sure\nyou've covered all the options.\n\nFor power users, the original flag-based interface is still available for a faster, scripted experience.\n\n### Configuration\n\n`tbdflow` is configurable via two optional files in the root of your repository. To get started quickly, run\n`tbdflow init` to generate default versions of these files.\n\n`.tbdflow.yml`\nThis file controls the core workflow of the tool. You can customise:\n\n- The name of your main branch (e.g. main, trunk).\n- Allowed branch types and their prefixes (e.g feat/, chore/)\n- A strategy for handling issue references (\"branch-name\" or \"commit-scope\")\n- The threshold for stale branch warnings.\n- Automatic tagging formats.\n- Commit message linting rules.\n\n\u003e **Note:** `main_branch_name` configures which branch is your trunk (typically `main` or `master`).\n\u003e tbdflow assumes this branch accepts direct commits. For protected branches, use short-lived feature branches with\n`tbdflow branch`.\n\n`.dod.yml`\nThis file controls the interactive Definition of Done checklist for the commit command.\n\n### Features\n\n#### The Definition of Done (DoD) Check\n\nMost teams have a Definition of Done. Most of the time, it lives in a wiki nobody opens mid-task.\n\nIf you add a `.dod.yml` to your repo, `tbdflow commit` will surface the checklist right when it matters, before you\npush. It's optional, non-blocking, and stays out of your way when you don't need it.\n\n**Example** `.dod.yml`:\n\n```\n# .dod.yml in your project root\nchecklist:\n  - \"All relevant automated tests pass successfully.\"\n  - \"New features or fixes are covered by new tests.\"\n  - \"Security implications of this change have been considered.\"\n  - \"Relevant documentation (code comments, READMEs) is updated.\"\n```\n\nIf you skip items, `tbdflow` offers to add a TODO list to the commit footer so the incomplete work is tracked in\nGit history, not lost in a chat thread.\n\n#### Commit Message Linting\n\nYour `.tbdflow.yml` can include linting rules that catch issues before the commit happens: subject too long, wrong\ntype, missing scope. Quick feedback, no surprises in the log later.\n\n**Default linting rules:**\n\n```yaml\nlint:\n  conventional_commit_type:\n    enabled: true\n    allowed_types:\n      - build\n      - chore\n      - ci\n      - docs\n      - feat\n      - fix\n      - perf\n      - refactor\n      - revert\n      - style\n      - test\n  issue_key_missing:\n    enabled: false\n    pattern: ^[A-Z]+-\\d+$\n  scope:\n    enabled: true\n    enforce_lowercase: true\n  subject_line_rules:\n    max_length: 72\n    enforce_lowercase: true\n    no_period: true\n  body_line_rules:\n    max_line_length: 80\n    leading_blank: true\n```\n\n#### Intent Log\n\nYou tried three approaches before settling on the final one. By the time you commit, the first two are gone. From\nyour memory and from the diff. A week later, a reviewer suggests one of the approaches you already rejected.\n\nThe Intent Log fixes this. While you work, you drop one-line breadcrumbs. At commit time, they're woven into the\nmessage body automatically. Zero context-switching, full context for whoever reads the commit next.\n\n**Start a task (optional):**\n\n```bash\ntbdflow task start \"Refactor auth logic\"\n```\n\n**Leave notes as you work:**\n\n```bash\ntbdflow note \"tried factory pattern, felt too verbose\"\ntbdflow + \"switching to a simple trait implementation\"\ntbdflow n \"trait approach is cleaner, keeping it\"\n```\n\nThe `note` command has two shorthand aliases: `+` and `n`.\n\n**Notes are consumed at commit time:**\n\nWhen you run `tbdflow commit`, the notes are appended to the commit body automatically:\n\n```\nfeat(auth): implement trait-based auth logic\n\nIntent Log:\n- tried factory pattern, felt too verbose\n- switching to a simple trait implementation\n- trait approach is cleaner, keeping it\n```\n\n**Other task commands:**\n\n```bash\ntbdflow task show    # Show the current task and notes\ntbdflow task clear   # Discard the current intent log\n```\n\n**Branch awareness:**\n\nThe intent log tracks which branch it belongs to. If you switch branches, tbdflow warns you about the stale log so\nnotes from one task don't leak into another commit.\n\n**File:** Notes are stored locally in `.tbdflow-intent.json` (git-ignored, never committed). The file is deleted\nautomatically after a successful push to trunk or after `tbdflow complete`.\n\n---\n\n## Global options\n\n| Flag      | Description                                              | Required |\n|-----------|----------------------------------------------------------|----------|\n| --verbose | Prints the underlying Git commands as they are executed. | No       |\n| --dry-run | Simulate the command without making any changes.         | No       |\n\n## Commands\n\n### 1. `commit`\n\nThis is the primary command for daily work.\n\nCommits staged changes using a Conventional Commits message. This command is context-aware:\n\n* **On `main`:** It runs the full TBD workflow: pulls the latest changes with rebase, commits, and pushes.\n* **On any other branch:** It simply commits and pushes, allowing you to save work-in-progress.\n\n**Usage:**\n\n```bash\ntbdflow commit [options]\n```\n\n**Options:**\n\n| Flag | Option                 | Description                                              | Required |\n|------|------------------------|----------------------------------------------------------|----------|\n| -t   | --type                 | The type of commit (e.g., feat, fix, chore).             | Yes      |\n| -s   | --scope                | The scope of the changes (e.g., api, ui).                | No       |\n| -m   | --message              | The descriptive commit message (subject line).           | Yes      |\n|      | --body                 | Optional multi-line body for the commit message.         | No       |\n| -b   | --breaking             | Mark the commit as a breaking change.                    | No       |\n|      | --breaking-description | Provide a description for the 'BREAKING CHANGE:' footer. | No       |\n|      | --tag                  | Optionally add and push an annotated tag to this commit. | No       |\n|      | --issue                | Optionally add an issue reference to the footer.         | No       |\n|      | --no-verify            | Bypass the interactive DoD checklist.                    | No       |\n\n**Example:**\n\n```bash\n# A new feature\ntbdflow commit -t feat -s auth -m \"add password reset endpoint\"\n\n# A bug fix with a breaking change\ntbdflow commit -t fix -m \"correct user permission logic\" -b\ntbdflow commit -t refactor -m \"rename internal API\" --breaking --breaking-description \"The `getUser` function has been renamed to `fetchUser`.\"\n\n# A bug fix with a new tag\ntbdflow commit -t fix -m \"correct user permission logic\" --tag \"v1.1.1\"\n```\n\n### 2. `branch`\n\nCreates and pushes a new, short-lived branch from the latest version of `main`. This is the primary command for starting\nnew work that isn't a direct commit to `main`.\n\n**Usage:**\n\n```bash\ntbdflow branch --type \u003ctype\u003e --name \u003cname\u003e [--issue \u003cissue-id\u003e] [--from_commit \u003ccommit hash\u003e]\n```\n\n**Options (release):**\n\n| Flag              | Description                                                                     | Required |\n|-------------------|---------------------------------------------------------------------------------|----------|\n| -t, --type        | The type of branch (e.g. feat, fix, chore). See .tbdflow.yml for allowed types. | Yes      |\n| -n, --name        | A short, desriptive name for the branch.                                        | Yes      |\n| --issue           | Optional issue reference to include in the branch name or commit scope.         | No       |\n| -f, --from_commit | Optional commit hash on `main` to branch from.                                  | No       |\n\n**Examples:**\n\n```bash\n# Create a simple feature branch named \"feat/new-dashboard\"\ntbdflow branch -t feat -n \"new-dashboard\"\n\n# Create a fix branch with an issue reference in the name\n# (This will be named \"fix/PROJ-123-login-bug\" by default)\ntbdflow branch -t fix -n \"login-bug\" --issue \"PROJ-123\"\n\n# Create a release branch from a specific commit\ntbdflow branch -t release -v \"2.1.0\" -f \"39b68b5\"\n```\n\n### 3. `complete`\n\nMerges a short-lived branch back into main, then deletes the local and remote copies of the branch.\n\n**Automatic Tagging:**\n\n* When completing a release branch, a tag (e.g. v2.1.0) is automatically created and pushed.\n\n**Usage:**\n\n```bash\ntbdflow complete --type \u003cbranch-type\u003e --name \u003cbranch-name\u003e\n```\n\n**Options:**\n\n| Flag | Option | Description                                      | Required |\n|------|--------|--------------------------------------------------|----------|\n| -t   | --type | The type of branch: feature, release, or hotfix. | Yes      |\n| -n   | --name | The name or version of the branch to complete.   | Yes      |\n\n**Examples:**\n\n```bash\n# Complete a feature branch\ntbdflow complete -t feat -n \"user-profile-page\"\n\n# Complete a release branch (this will be tagged v2.1.0)\ntbdflow complete -t release -n \"2.1.0\"\n```\n\n### 4. `changelog`\n\nGenerates a changelog in Markdown format from your repository's Conventional Commit history. See `tbdflow` repo for a\nCHANGELOG.md generated by this command.\n\n**Usage:**\n\n```bash\ntbdflow changelog [options]\n```\n\n**Options:**\n\n| Option       | Description                                                               |\n|--------------|---------------------------------------------------------------------------|\n| --unreleased | Generate a changelog for all commits since the last tag.                  |\n| --from       | Generate a changelog for commits from a specific tag.                     |\n| --to         | Generate a changelog for commits up to a specific tag (defaults to HEAD). |\n\n**Examples:**\n\n```bash\n# Generate a changelog for a new version\ntbdflow changelog --from v0.12.0 --to v0.13.0\n\n# See what will be in the next release\ntbdflow changelog --unreleased\n```\n\n### 5. `review`\n\nManages non-blocking post-commit reviews for trunk-based development. In TBD, code is committed to trunk first and\nreviewed asynchronously, this command facilitates that workflow by creating GitHub issues for review tracking.\n\n**Philosophy:**\n\nIn Trunk-Based Development, reviews are for **course correction** and **knowledge sharing**, not gatekeeping.\nCode is already in trunk; reviewers focus on Intent, Impact, and Insight.\n\n**Usage:**\n\n```bash\ntbdflow review [sha] [options]\n```\n\n**Options:**\n\n| Option                | Description                                                            |\n|-----------------------|------------------------------------------------------------------------|\n| \\\u003csha\\\u003e               | Trigger a review for a specific commit (positional argument).          |\n| --trigger             | Create a review request for the current HEAD commit.                   |\n| --digest              | Generate a digest of commits needing review.                           |\n| --approve \\\u003chash\\\u003e    | Mark a commit as approved (closes issue with `review-accepted`).       |\n| --concern \\\u003chash\\\u003e    | Raise a concern on a commit (keeps issue open, adds `review-concern`). |\n| --dismiss \\\u003chash\\\u003e    | Dismiss a review (closes issue with `review-dismissed`).               |\n| -m, --message         | Message for concern or dismiss (required with --concern/--dismiss).    |\n| --since \\\u003ctime\\\u003e      | Time range for digest (default: \"1 day ago\").                          |\n| --reviewers \\\u003cusers\\\u003e | Override default reviewers (comma-separated GitHub usernames).         |\n\n**Examples:**\n\n```bash\n# Create a review issue for a specific commit\ntbdflow review abc1234\n\n# Create a review issue for the latest commit (HEAD)\ntbdflow review --trigger\n\n# See commits from the last 3 days that may need review\ntbdflow review --digest --since \"3 days ago\"\n\n# Mark a commit as reviewed (closes the associated GitHub issue)\ntbdflow review --approve abc1234\n\n# Raise a concern on a commit (keeps issue open, notifies author)\ntbdflow review --concern abc1234 -m \"Potential thread safety issue\"\n\n# Dismiss a review without fixing (closes issue)\ntbdflow review --dismiss abc1234 -m \"Won't fix, out of scope\"\n```\n\n#### Review Labels (Nuanced Statuses)\n\n`tbdflow` uses configurable labels to track review status throughout the lifecycle:\n\n| Label              | Description                                     | Issue State |\n|--------------------|-------------------------------------------------|-------------|\n| `review-pending`   | Review awaiting attention (default on creation) | Open        |\n| `review-concern`   | Concern raised - needs attention from author    | Open        |\n| `review-accepted`  | Review approved                                 | Closed      |\n| `review-dismissed` | Review dismissed (won't fix)                    | Closed      |\n\n**Concern Workflow:**\n\nWhen you raise a concern with `--concern`:\n\n1. The issue label changes from `review-pending` to `review-concern`\n2. A comment is added to the issue with the concern message\n3. A checklist item is appended to the issue body: `- [ ] \u003cconcern\u003e`\n4. (Optional) A commit status is set based on `concern_blocks_status` config\n\nThis is **always non-blocking**, concerns are informational and encourage fix-forward patterns.\n\n**Configuration:**\n\nEnable the review system in your `.tbdflow.yml`:\n\n```yaml\nreview:\n  enabled: true\n  strategy: github-issue  # or \"github-workflow\" or \"log-only\"\n  default_reviewers:\n    - teammate-username\n    - another-reviewer\n\n  # Optional: Customise label names (defaults shown)\n  labels:\n    pending: \"review-pending\"\n    concern: \"review-concern\"\n    accepted: \"review-accepted\"\n    dismissed: \"review-dismissed\"\n\n  # Optional: Set commit status to 'failure' when concern is raised\n  # If false (default), status is 'pending' with description\n  concern_blocks_status: false\n```\n\n**Commit Status Behaviour:**\n\nWhen `concern_blocks_status` is configured:\n\n| Setting           | Status State | Description                                   |\n|-------------------|--------------|-----------------------------------------------|\n| `false` (default) | `pending`    | \"Awaiting fix-forward for concern: [message]\" |\n| `true`            | `failure`    | \"Audit Concern: [message]\"                    |\n\n#### Targeted Review Rules\n\nFor teams that need specific reviewers for certain files or directories, you can configure **review rules** with glob\npatterns. When rules are configured, reviews are **automatically triggered** after a commit if any changed files match\na rule pattern. The appropriate reviewers are assigned based on the matching rules.\n\nThis allows:\n\n- **Opt-in by Default**: Without rules, `tbdflow review --trigger` is manual\n- **Auto-trigger with Rules**: When rules are configured and files match, reviews are triggered automatically after\n  commit\n- **Smart Routing**: Database changes go to the DB expert, infrastructure changes go to DevOps, etc.\n\n```yaml\nreview:\n  enabled: true\n  strategy: github-issue\n  default_reviewers:\n    - cladam\n\n  rules:\n    # Database changes get reviewed by the DB expert\n    - pattern: \"migrations/**\"\n      reviewers: [ \"db-expert\" ]\n\n    # Targeted review for infrastructure changes\n    - pattern: \"infra/*.tf\"\n      reviewers: [ \"devops-lead\" ]\n\n    # Targeted review for critical security modules\n    - pattern: \"src/auth/**\"\n      reviewers: [ \"security-officer\" ]\n```\n\n**Rule Options:**\n\n| Field       | Description                                                              | Required |\n|-------------|--------------------------------------------------------------------------|----------|\n| `pattern`   | Glob pattern for files that trigger this rule (e.g., `src/auth/**`)      | Yes      |\n| `reviewers` | List of reviewers specifically for these files (uses default if not set) | No       |\n\n**Strategies:**\n\n| Strategy          | Description                                            | Best For                             |\n|-------------------|--------------------------------------------------------|--------------------------------------|\n| `github-issue`    | CLI creates GitHub issues directly                     | Small teams, simple setup            |\n| `github-workflow` | CLI triggers GitHub Actions for server-side management | Regulated environments, audit trails |\n| `log-only`        | Local logging only, no external integration            | Offline or air-gapped environments   |\n\n\u003e **Note:** Both `github-issue` and `github-workflow` strategies require the [GitHub CLI (\n`gh`)](https://cli.github.com/)\n\u003e to be installed and authenticated.\n\n#### Server-Side Reviews with GitHub Actions\n\nFor teams that need **commit status gates**, **full audit trails**, or **multi-reviewer orchestration**, use the\n`github-workflow` strategy. This triggers a GitHub Actions workflow that:\n\n1. Creates review issues (even if someone bypasses the CLI)\n2. Sets commit statuses (`pending` → `success`) for deploy gating\n3. Handles multi-reviewer consensus automatically\n\nTo set up:\n\n1. Copy `.github/workflows/nbr-review.yml.example` to `.github/workflows/nbr-review.yml`\n2. Configure your `.tbdflow.yml`:\n\n```yaml\nreview:\n  enabled: true\n  strategy: github-workflow\n  workflow: nbr-review.yml\n  default_reviewers:\n    - teammate-username\n```\n\n3. Run `tbdflow review --trigger` and the workflow handles the rest\n\n### 6. `task` and `note`\n\nThink of these as your development scratch pad. Start a task, jot down what you're trying and why, and let the\ncommit pick it all up when you're ready.\n\n**Usage:**\n\n```bash\ntbdflow task start \u003cdescription\u003e   # Start a named task\ntbdflow task show                  # Show current task and notes\ntbdflow task clear                 # Discard the intent log\n\ntbdflow note \u003cmessage\u003e             # Log a note\ntbdflow + \u003cmessage\u003e                # Shorthand alias\ntbdflow n \u003cmessage\u003e                # Shorthand alias\n```\n\n**Options (`note`):**\n\n| Flag   | Description                                          | Required |\n|--------|------------------------------------------------------|----------|\n| --show | Show the current intent log instead of adding a note | No       |\n\n**Examples:**\n\n```bash\n# Start a task and leave breadcrumbs\ntbdflow task start \"Refactor auth module\"\ntbdflow + \"tried decorator pattern, too much boilerplate\"\ntbdflow + \"simple middleware chain works better\"\n\n# View what you've captured\ntbdflow task show\n\n# Notes are automatically included when you commit\ntbdflow commit -t refactor -s auth -m \"simplify auth middleware\"\n# The commit body will contain:\n#   Intent Log:\n#   - tried decorator pattern, felt too verbose\n#   - simple middleware chain works better\n```\n\n### 7. `radar`\n\nScans active remote branches for overlapping work that may cause merge conflicts with your local changes. This is the\n**social coding safety net** for Trunk-Based Development, it makes the invisible visible by showing who else is\ntouching the same files before you push.\n\nIn TBD, everyone integrates frequently. The biggest fear is two people editing the same lines simultaneously. Standard\nGit won't warn you until you try to push. Radar warns you *before* you commit.\n\n**Usage:**\n\n```bash\ntbdflow radar\n```\n\n**Detection Levels** (configurable in `.tbdflow.yml`):\n\n| Level  | What it checks                        | Speed        |\n|--------|---------------------------------------|--------------|\n| `file` | Same files touched (default)          | ~5ms/branch  |\n| `line` | Overlapping line ranges in same files | ~50ms/branch |\n\n**Example output:**\n\n```\nOVERLAP DETECTED with 1 active branch(es):\n\n  feat/API-42-user-auth (by @alice, 2 commits ahead)\n  ├── src/auth/handler.rs    LINE OVERLAP\n  └── src/auth/middleware.rs  SAME FILE\n\n  3 other active branch(es) have no overlap with your changes.\n\nHint: Coordinate with the overlapping author(s) before pushing.\n```\n\n**Integration:**\n\nRadar is also integrated into other commands:\n\n* **`tbdflow sync`** automatically shows a one-liner warning if overlap is detected.\n* **`tbdflow commit`** optionally warns or prompts for confirmation before committing (configurable).\n\n**Configuration:**\n\n```yaml\nradar:\n  enabled: true\n  level: file          # file | line\n  on_sync: true        # Show warnings during tbdflow sync\n  on_commit: warn      # off | warn | confirm\n  ignore_patterns: # Files to exclude from overlap detection\n    - \"*.lock\"\n    - \"*-lock.*\"\n    - \"CHANGELOG.md\"\n```\n\n### 8. Pre-flight CI check\n\nWhen enabled, `tbdflow sync` checks the CI status of the trunk (via the `gh` CLI) **before** pulling.\nIf the trunk is red or pending, you get a prompt instead of blindly pulling a broken build.\n\n**Configuration:**\n\n```yaml\nci_check:\n  enabled: true   # default: false\n```\n\n**Behaviour:**\n\n| Trunk CI status | What happens                                            |\n|-----------------|---------------------------------------------------------|\n| Green           | Silent proceed, prints a brief confirmation             |\n| Failed          | Warns and prompts: \"Continue with sync? (y/N)\"          |\n| Pending         | Informs and prompts: \"Pull anyway? (y/N)\"               |\n| Unknown         | Proceeds silently (e.g. `gh` not installed, no CI runs) |\n\n\u003e Requires the [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated.\n\n### 9. Utility commands\n\nNot part of the core workflow, but handy for checking on things:\n\n**Examples:**\n\n```bash\n# Does a pull, shows latest changes to main branch, and warns about stale branches.\n# If ci_check is enabled, checks trunk CI status first.\ntbdflow sync\n\n# Inspect your current configuration\ntbdflow info\n\n# Checks the status of the working dir\ntbdflow status\n\n# Shows the current branch name\ntbdflow current-branch\n\n# Explicitly checks for local branches older than one day.\ntbdflow check-branches\n\n# Checks for a new version of tbdflow and updates it if available.\ntbdflow update\n```\n\n#### `undo`\n\nIn TBD, the rule is simple: if the trunk breaks, fix it or revert it immediately. `tbdflow undo` is a smart wrapper\naround `git revert` that syncs with the remote, verifies the commit is on the trunk, cleanly reverts it, and pushes,\nall in one command.\n\n**Usage:**\n\n```bash\ntbdflow undo \u003csha\u003e [options]\n```\n\n**Options:**\n\n| Flag      | Description                                       | Required |\n|-----------|---------------------------------------------------|----------|\n| --no-push | Create the revert commit locally without pushing. | No       |\n\n**Examples:**\n\n```bash\n# Revert a specific commit on the trunk\ntbdflow undo abc1234\n\n# Revert locally without pushing (e.g. to inspect the result first)\ntbdflow undo abc1234 --no-push\n\n# Preview what would happen without making changes\ntbdflow --dry-run undo abc1234\n```\n\n### 10. Advanced Usage\n\n#### Shell Completion\n\nAdd tab-completion to your shell:\n\nFor Zsh (`~/.zshrc`):\n\n```bash\neval \"$(tbdflow generate-completion zsh)\"\n```\n\nFor Bash (`~/.bashrc`):\n\n```bash\neval \"$(tbdflow generate-completion bash)\"\n```\n\nFor Fish (`~/.config/fish/config.fish`):\n\n```bash\ntbdflow generate-completion fish | source\n```\n\n#### Man Page\n\n```bash\ntbdflow generate-man-page \u003e tbdflow.1 \u0026\u0026 man tbdflow.1\n```\n\n## IDE support\n\n`tbdflow` comes with IDE support for:\n\n- [IntelliJ](https://github.com/cladam/tbdflow/tree/main/plugins/intellij)\n- [VS Code](https://github.com/hekonsek/tbdflow-vscode-extension)\n\n## Contributing\n\nFirst off, thank you for considering contributing to `tbdflow`! ❤️\n\nPlease feel free to open an issue or submit a pull request.\n","funding_links":["https://paypal.me/ClaesAdamsson"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcladam%2Ftbdflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcladam%2Ftbdflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcladam%2Ftbdflow/lists"}