Skip to main content

Best practices

Keep main reviewable​

Use branches for meaningful changes, especially AI-generated changes. Merge only after reviewing additions, modifications, deletions, conflicts, and link proposals.

Intent branches merge by themselves after their pull requests merge, so the review point for that work is the pull request. Set a hold when you want to review the branch first. See Hold an automatic merge.

Use components consistently​

Components are the backbone for traceability and risk. Keep the component list short, stable, and product-oriented.

Good components:

  • Billing.
  • Authentication.
  • Search.
  • Notifications.

Weak components:

  • Sprint 19.
  • Misc.
  • Fixes.
  • Temporary.

Link test cases to specs when tests are created. Waiting until release review makes traceability less useful and creates avoidable gate failures.

Preserve source provenance​

Add spec sources for requirements documents, customer asks, code references, and agent artifacts. Sources help reviewers understand why a spec exists.

Align release strings​

Use the same release value everywhere:

  • CI release creation.
  • Runtime telemetry SDK.
  • Source map upload.
  • Quality gate checks.

Keep secrets separated​

  • API tokens belong in secret stores or ~/.tiden/config.json.
  • DSNs belong in app runtime config.
  • Workspace credentials belong in Tiden's credential vault.
  • Source map upload tokens belong only in CI.

Treat generated branches as proposals​

Do not merge agent output because it is generated. Inspect the source evidence, change diff, quality impact, and conflicts. This applies to the branches that agent runs and imports create. Intent branches merge by themselves, and the merged branch tells you when its Quality Gate was red or its closing pass was skipped.

Use risk acceptance sparingly​

Risk acceptance is a business decision. Include a clear reason and approval when shipping with a soft failure.