Adding a feature

The standard playbook.

0. Start with an issue

Either pick an existing sub-issue under an epic (#78–#81) or create one using the Feature Request template. Link the parent epic.

Do not start coding without an issue. Agents that work without a tracked issue make changes that slip through review.

1. Branch + flag

git fetch origin main
git switch -c feature/<short-name> origin/main

Always branch from origin/main. Never branch from another PR's branch or a worktree-agent-* branch. Branching from a feature branch silently includes that branch's commits in your PR and can cause ghost merges. On 2026-04-25 (incident

330) this caused content loss; on 2026-04-29 (#457) it contaminated an unrelated

PR with dep-bump commits. The CI job base_branch_lint in ci-pr.yml will block your PR if contamination is detected.

Name feature flags FLAG_<SCREAMING_SNAKE> and add them to backend_v2/api/feature_flags.yaml with a default of false. Don't skip the flag for "small" features — a flag is your rollback path.

2. Code + tests in the same commit

• Backend: add tests under backend_v2/tests/. Copy the shape of test_smoke_api.py for route tests.
• Frontend: add tests under frontend/trademaster_ui/src/**/__tests__/ next to the code.
• Do not merge feature code without the test that proves it works.

3. Run locally

./scripts/agent-tools/run_smoke.sh  # full smoke sweep
python -m pytest backend_v2/tests -q  # backend unit + integration
npm --prefix frontend/trademaster_ui test -- --watchAll=false  # frontend

Playwright-driven UI verification is preferred when the feature has a visible component. Don't claim a feature works without actually loading it in a browser (headless or headed).

4. Security sanity

Before opening a PR, think about each of these and note them in the PR template:

• Auth / credentials touched?
• Order submission / broker integration touched?
• New external HTTP call or data source?
• New dependency?

If any "yes," expect the security-* CI jobs to scrutinize your PR. Bandit + pip-audit + npm audit + gitleaks run on every push.

5. Open the PR

Fill in the template completely. The sections aren't optional:

• What — 1-3 sentences.
• Why — link the issue.
• How to test — commands/URLs a reviewer runs in ≤2 min.
• Security — real answer, not "N/A".
• Flag — name the flag or justify no flag.

6. CI

CI runs: - backend-tests — pytest - frontend-tests — jest - security-deps — pip-audit + npm audit - security-sast — bandit - security-secrets — gitleaks

HIGH/CRITICAL findings block merge. If the finding is a false positive, document the suppression in the PR and link the rule that generated it. Do not blindly add suppressions.

7. Merge

• One human review minimum (or designated agent review)
• CI green on all 5 jobs
• Flag defaulted to false unless we're ready to release

After merge, the flag stays false until a follow-up flip. That follow-up is its own PR with a "flip FLAG_X to true" title, so the release has an audit trail.

8. Close the loop

• Close the issue (auto via "Closes #N" in commit message)
• Update the parent epic checklist if applicable
• Note any lessons in docs/agents/onboarding.md so the next agent benefits