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: | Source | Automation | What it detects | |---|---|---| | Production errors | Incident Responder | Sentry errors (every 15 min) | | Post-deploy regressions | Post-Merge Verifier | Smoke test failures (on PR merge) | | Design violations | UI Verifier | Design spec mismatches + Storybook visual regressions (on PR merge) | | Performance degradation | Performance Monitor | Latency/error/size regressions (weekly) | 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 | Automation | Trigger | Role | |---|---|---| | Feature Planner | Manual | Triages unlabeled issues, decomposes specs into issues | | Feature Builder | Cron (30 min) | Implements features/enhancements from backlog | | Bug Fixer | Cron (30 min) | Implements bug fixes from backlog | | PR Reviewer | Cron (15 min) | Reviews and merges PRs | | PR Shepherd | Cron (6 hours) | Cleans up stale/conflicted PRs | | Incident Responder | Cron (15 min) | Triages Sentry errors into bug issues | | Post-Merge Verifier | On PR merge | Smoke-tests production after merge | | UI Verifier | On PR merge | Checks design spec compliance | | Performance Monitor | Weekly | Checks latency, errors, build size | | Needs-Human Requeue | Cron (30 min) | Re-queues issues after user responds | | Automation Auditor | Weekly | Audits label hygiene, doc freshness | | Daily Metrics | Daily | Snapshots project metrics | | Weekly Recap | Weekly | Summarizes week's progress | ## 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 ```