Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Develop: Branch and Spec

Work on features with proper branch isolation and keep your specs in sync with the code.

Work branches with fledge work

Instead of manually creating branches and PRs, fledge work handles the git ceremony for you.

# Start a work branch (defaults to feat/ type)
fledge work start add-auth

# Start a bug fix branch
fledge work start login-crash --branch-type fix

# Link to a GitHub issue
fledge work start login-crash --branch-type fix --issue 42

# Check where you are
fledge work status

# Open a PR when ready
fledge work pr --title "Add auth middleware"

This creates a branch using your configured format (default: {author}/{type}/{name}), and fledge work pr opens a pull request against your base branch with sensible defaults.

Options for work start:

  • -t, --branch-type <TYPE> - Branch type: feat, feature, fix, bug, chore, task, docs, hotfix, refactor [default: feat]
  • -i, --issue <NUMBER> - Link to GitHub issue (prefixes branch name with issue number)
  • --prefix <PREFIX> - Override branch prefix entirely (e.g. user/leif)
  • --base <branch> - Base branch (defaults to main)

Options for work pr:

  • -t, --title <title> - PR title
  • -b, --body <body> - PR description
  • --draft - Open as draft
  • --base <branch> - Target branch

Spec-sync with fledge spec

Specs are markdown files in specs/ that define how a module should work. fledge spec check validates that the code matches the spec.

# Set up spec-sync
fledge spec init

# Create a new spec
fledge spec new auth

# Check specs against code
fledge spec check
fledge spec check --strict   # warnings become errors

Spec format

Each spec is a markdown file with a YAML frontmatter block:

---
module: auth
version: 1
status: active
---

# Auth Module

Description of what this module does.

## Public API

List the public functions/types and what they do.

## Invariants

Any guarantees the code must uphold.

fledge reads the frontmatter to track the module name, version, and status. The body is free-form markdown.

Validation rules

fledge spec check verifies:

  1. Every spec in specs/ has a corresponding source file (no orphaned specs)
  2. Every tracked module has a spec (no undocumented modules)
  3. Spec frontmatter is valid YAML with required fields (module, version, status)
  4. Version field is present (integer)

With --strict, warnings (missing optional fields, minor drift) become errors.

Workflow

Write the spec first, then write the code to match. Before committing, run:

fledge spec check

Add it to your CI lane:

[lanes.ci]
steps = ["fmt", "lint", "test", "spec-check"]

[tasks.spec-check]
cmd = "fledge spec check"

The .specsync/hashes.json file tracks content hashes. Commit it alongside spec changes so CI can detect drift.