# 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.

```bash
# 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`, `fix`, `chore`, `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.

```bash
# 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 TOML frontmatter block:

```markdown
---
module = "auth"
version = "1.0.0"
---

# 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 and version. 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 TOML
4. Version field is present and follows semver

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

### Workflow

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

```bash
fledge spec check
```

Add it to your CI lane:

```toml
[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.
