Developer Workflow

Overview

Codeberg is the single source of truth for project management. All work — features, bugs, chores, documentation — is tracked via issues and milestones. roadmap.yaml and feature pages are derived artifacts maintained by CI, never edited manually.

See ADR-023 for the architectural decision behind this workflow.

Getting Started

Repository: codeberg.org/weltenwanderer/weltenwanderer

Required tools:

Tool	Purpose
`fj`	Forgejo CLI — issue and PR management
`bun`	Runtime, package manager, test runner
`git`	Version control with worktree support

Authentication:

fj auth login

Picking Up Work

Check open milestones and pick an issue:
Terminal window
```
fj issue search
```
Read the issue details and any attached plan:
Terminal window
```
fj issue view <N>
```

Create a worktree for the issue:

git worktree add .claude/worktrees/<branch-name> -b <branch-name>

If no plan is attached to the issue, create one before implementing.

Branch naming convention:

feature/<N>-<slug>
fix/<N>-<slug>
chore/<N>-<slug>

N is the issue number (no hash prefix). slug is lowercase kebab-case.

Making Changes

Read the relevant allium specs in packages/*/specs/ and specs/ for behavioral requirements.
Implement against the spec rules.
Write tests (TDD: red, green, refactor).
Verify locally:
Terminal window
```
bun test
```

Committing and PRs

Commit format — always reference the issue number:

type(scope): description (#N)

Examples:

feat(lsp): add semantic tokens (#42)
fix(validation): handle empty decide block (#57)
docs(guide): update CLI usage (#63)

Push and create a PR:

git push -u origin <branch-name>
fj pr create -aA

The PR body must include Closes #N so Forgejo auto-closes the issue on merge.

Merge strategy: Rebase + fast-forward only. No merge commits. Every commit on main references an issue.

Issue Templates

Four templates are available when creating issues on Codeberg:

Template	Required Field
Bug Report	What happened?
Feature Request	What becomes possible?
Chore	What and why?
Documentation	What’s missing, stale, or incorrect?

All templates include a privacy checkbox. Codeberg issues are public — do not include credentials, personal data, or internal paths.

Labels

Kind — what type of work:

Label	Use
`Kind/Feature`	Roadmap feature
`Kind/Bug`	Defect
`Kind/Enhancement`	Improvement to existing feature
`Kind/Chore`	Maintenance, tooling, config
`Kind/Documentation`	Docs-only change
`Kind/Security`	Security-related

Status — flow state:

Label	Use
`Status/Blocked`	Dependency not resolved
`Status/Deferred`	Parked deliberately (Backlog milestone)
`Status/Abandoned`	Stale, no activity (auto-closed after 21 days)
`Status/Needs Info`	Waiting on reporter (auto-closed after 30 days)

Priority — urgency:

Label	Use
`Priority/Critical`	Drop everything
`Priority/High`	Next up
`Priority/Medium`	This milestone
`Priority/Low`	When time permits

Milestones

Milestones map to implementation phases and parallel tracks:

Milestone	State
Phase 1: LLM Skill	Closed
Phase 2: Grammar & Parser	Closed
Phase 3: Core Validation	Closed
Phase 4: Emmett Generator	Closed
Phase 5: CLI	Open
Phase 6: Language Server	Open
Mermaid Diagram Generation	Open
Backlog	Open (no due date)

Every issue belongs to a milestone, including small bugs and chores.

Reporting Bugs or Gaps

When you discover something that needs attention:

Create an issue on Codeberg using the appropriate template.
Assign it to the relevant milestone.
Apply Kind/* and Priority/* labels.

If working in a Claude Code session, the agent presents a dialog to create the issue via fj — approve or decline with one response.

CI/CD

On PR (pre-merge):

Check	Blocks merge?
`bun test`	Yes
Type check (`tsc --noEmit`)	Yes
Commit format (issue reference `#N`)	Yes
Merge strategy (rebaseable, ff-only)	Yes
Blast radius analysis	No (informational PR comment)

Post-merge to main:

Job	What it does
Status sync	Reads merged commit issue references, updates `roadmap.yaml`, regenerates feature pages
Planned marker cleanup	Scans docs for stale `:::note[Planned]` markers, opens PR to remove them
Release gate	Semantic-release flow (unchanged)

Weekly:

Job	What it does
Zombie patrol	Auto-closes `Status/Abandoned` issues older than 21 days and `Status/Needs Info` issues older than 30 days