2-Way binding between code and user stories- Magic by Vibe coding CLIs

How our team Improved Flutter Project Productivity & Management with Two-Way Bound User Stories and CLI Automation

While building trackMyPetition™, an AI-powered petition tracking platform, our team explored a better way to handle the often-fragmented workflow between product management and development.

Instead of separating specs, code, and tests across tools and teams, we adopted a two-way binding pattern—where structured user stories live in the codebase, are version-controlled, and drive everything from UI to logic and automated test coverage.

The Pattern: User Stories as the Source of Truth

Each feature—be it passkey login, views—is defined via modular, structured user story files in a dedicated userstories/ directory. These stories aren't static documentation—they’re actively wired to code.

Whenever a user story is updated:

• Screen layouts, navigation flows, and business logic are auto-aligned,
• Test cases are auto-generated or updated,
• All changes are logged directly in the story file, complete with file paths, timestamps, and rationale.

This ensures that implementation, testing, and documentation remain in lockstep, making the codebase self-describing and auditable.

Two-Way Binding in Action

Using a CLI-first workflow (with Vibe Coding CLI and Makefile-driven tooling):

• Devs work on atomic, trackable user stories.
• CLI enforces sync between story specs and implementation.
• Responsive widgets are reused across screens for consistency.
• Implementation history is stored inside the user story file under ## Implementation Notes.

It’s a workflow where product design and engineering speak the same language—through the repo.

Why This Worked

• Improved Productivity: No switching between Notion/Jira and IDE. Stories are the spec and drive the build.
• Greater Confidence: Everything built maps directly to acceptance criteria.
• Developer Clarity: No ambiguity about what's done, what's pending, or what changed. userstories in /userstories became source of truth
• PM Traceability: Implementation changes tied back to features, always up-to-date.
• Onboarding Ease: New devs can trace features directly from story to screen.

Tooling That Helped

• Flutter: For fast, platform-agnostic UI development.
• Reusable Components: Widgets created for reuse and responsiveness.
• Makefile CLI: For standardized commands like test, build, and story sync.
• Environment Variable Management: To support multiple staging and prod environments.
• In-repo User Story Tracking: As the single source of feature truth.

Final Thoughts

This approach not only helped us build trackMyPetition™ faster and cleaner—it’s also a highly adaptable pattern for any small or scaling team using Flutter or any modern framework.

Whether you're building a startup MVP or maintaining a complex product, this user story–bound architecture enables continuous alignment between design, code, and QA—without relying on bulky external tools.

If you're curious to implement something similar in your project, happy to share more.

#CLAUDE.md
# trackMyPetition™
trackMyPetition™ is AI-powered USCIS petition tracking software by TMP Labs LLC.
## Logo
assets/trackMyPetition.svg

## Application Structure

The application structure is defined through detailed user stories organized in the following directories:

- **Landing Page**: See [userstories/landingPage/](userstories/landingPage/)
  - [Product Features Display](userstories/landingPage/productFeaturesDisplay.md)
  - [Passkey Authentication Access](userstories/landingPage/passkeyAuthenticationAccess.md)
  - [Footer Information](userstories/landingPage/footerInformation.md)

## Technical Requirements

### Platform
- **Flutter Application**
- **Mobile Interface**: Limited to landing page, login
- **Tablet/Desktop**: Full petition creation and editing capabilities

### Development Standards
- **Comments**: Always place comments to the right of code (not above)
- **Theme**: Use colors from logo
- **Flutter widgets**- Create reusable widget at every opportunity
- **Common Components**: Use standardized reusable components across the application:
  - `FeatureCard`: For displaying features with icon, title, and description (responsive design)
  - Components should be defined in `widgets/` directory with camelCase naming
  - All reusable components must support responsive design patterns
- **Naming Convention**: Use camelCase for variables, functions, and file names
- **Build System**: Create Makefile for common development commands
- **Configuration settings**- All configuration settings would be defined through environment variables. If environment variables are not defined, they would read from .env
- **Test cases** - Automatically create and update test cases for all user stories
- **User Story Implementation** - When user stories in userstories/ directory are updated, automatically update the corresponding code implementation to match the new requirements. This includes:
  - Updating screen layouts and UI components
  - Modifying navigation flows and routing
  - Adjusting business logic and data models
  - Ensuring responsive design requirements are met
  - Maintaining consistency between user stories and implementation

- **Implementation Notes Tracking** - Automatically maintain implementation notes in user story files when code is updated:
  - Add "## Implementation Notes" section to each user story file
  - Record all code changes with timestamps and file paths
  - Include brief description of what was implemented/changed
  - Track component relationships and dependencies
  - Document responsive design implementations
  - Note any deviations from original user story requirements
  - Format: `- **[YYYY-MM-DD]** Updated `path/to/file.dart`: Brief description of change`
  - Keep implementation history for audit trail and maintenance
  - Link code changes back to specific acceptance criteria when applicable

## Authentication
- **Petitioner Login**: Auth0 passkey implementation
- **Attorney Login**: Auth0 passkey implementation        

#Flutter #DeveloperProductivity #DevTools #VibeCLI #CLIDrivenDevelopment #ProjectManagement #trackMyPetition #SoftwareEngineering #UserStories #Fullstack #MakefileMagic #TwoWayBinding