Development Workflow

Development Workflow

How to Submit a Feature Request

1. Create a GitHub Issue using the Feature Request template.
2. Fill in: description (what + why), priority, affected area.
3. The Feature Planner triages unlabeled issues on its next manual run:
   • If the issue has sufficient detail → labels are added (status:backlog + priority + type) and it enters the automation queue.
   • If detail is insufficient → needs-human label is added with a comment asking specific questions.
4. Respond to the questions. The Needs-Human Requeue automation detects your response (within 30 min) and removes needs-human.
5. The Feature Planner re-triages on its next run.
6. The Feature Builder picks up status:backlog issues and implements them.

How to Report a Bug

1. Create a GitHub Issue using the Bug Report template.
2. Fill in: description, steps to reproduce, expected vs actual, priority.
3. Same triage flow as features (Feature Planner → labels → queue).
4. The Bug Fixer picks up bug + status:backlog issues and fixes them.

How Bugs Get Fixed Automatically

Several automations detect bugs and create issues:

These automations create issues with bug + status:backlog labels. The Bug Fixer picks them up, implements a fix, and opens a PR. The PR Reviewer reviews and merges.

How Features Get Built Automatically

1. Feature Planner (manual trigger) triages unlabeled issues or decomposes the product spec into new issues with status:backlog labels.
2. Feature Builder (cron, every 30 min) picks up the highest-priority non-bug status:backlog issue, implements it, and opens a PR.
   • For UI components, the Feature Builder creates co-located *.stories.tsx files and runs visual regression tests (pnpm test:visual) to generate baselines.
3. PR Reviewer (cron, every 15 min) reviews the PR, fixes CI failures if needed, and merges. Checks that UI component PRs include Storybook stories.

The Full Automation Roster

Label Reference

Status labels (lifecycle)

• status:backlog — ready for automation pickup
• status:in-progress — being worked on by an automation or human
• status:in-review — PR open, awaiting review
• status:done — completed and merged

Priority labels

• priority:1 — foundation (blocks other work)
• priority:2 — core features (product value)
• priority:3 — polish (nice to have)

Type labels

• feature — new functionality
• enhancement — improvement to existing functionality
• bug — defect or regression
• chore — internal quality, no user-visible change
• performance — performance-related issue

Flag labels

• needs-human — needs user input; re-queue automation removes when user responds
• ona-user — PR created via interactive Ona session (no issue reference required)

Storybook and Visual Regression

Every UI component in src/components/ has a co-located *.stories.tsx file. Storybook serves as the visual source of truth for the design system.

For developers:

• Run pnpm storybook to browse components in isolation.
• When creating or modifying a component, update its story file.
• Run pnpm test:visual to check for visual regressions against committed baselines.
• After intentional visual changes, regenerate baselines with pnpm test:visual --update-snapshots.

For automations:

• The Feature Builder creates stories for new UI components and runs visual regression tests.
• The PR Reviewer checks that UI component PRs include corresponding stories.
• The UI Verifier runs Storybook visual regression after merge to detect unintended changes.
• The Bug Fixer updates stories and baselines when fixing UI bugs.

Issue Lifecycle

Created (unlabeled)
  → Feature Planner triages
    → Sufficient: status:backlog + priority + type
      → Feature Builder / Bug Fixer implements
        → status:in-progress
          → PR opened
            → status:in-review
              → PR Reviewer merges
                → status:done
    → Insufficient: needs-human + questions
      → User responds
        → Needs-Human Requeue removes needs-human
          → Feature Planner re-triages