The "Docs as Code" Development Workflow

This document outlines the standardized development lifecycle for this project. It is designed to ensure that documentation and code evolve together, creating a single source of truth and improving collaboration across all roles. The workflow leverages Git and the GitHub ecosystem (Issues, Projects, and Pull Requests) as its foundation.

Core Principles

• Living Documentation: All project artifacts (BRDs, TRDs, Test Plans, Code) are version-controlled in Git. They are treated as living documents that are updated continuously, not as static files that become obsolete.
• Single Source of Truth: The main branch of the Git repository is the definitive source for all current documentation and code. Technical documents describe the target state of the system, not a history of changes.
• Unified Review Process: A single Pull Request (PR) contains all changes related to a feature—including business requirements, technical designs, code, and test plans. This enables a holistic review process where all stakeholders can see the full context.

The Core Tools

• GitHub Issue: The "Task Center". Each new feature or significant change starts as an Issue. It is the single source of truth for what needs to be done and how it should be done, containing the user story, acceptance criteria, and a detailed developer checklist.
• GitHub Project: The "Visual Backlog". A Kanban-style board used to visualize and manage the workflow of all Issues. It provides an at-a-glance view of the sprint backlog and the status of each task (To Do, In Progress, In Review, Done).
• GitHub Pull Request (PR): The "Workspace & Review Hub". An ephemeral workspace for implementing the changes required by an Issue. It aggregates all document and code changes for review and discussion before they are merged into the main branch.

---

The End-to-End Workflow

This process describes the lifecycle of a single feature, from ideation to production deployment.

Phase 1: Definition & Planning

This phase is about translating a business need into a complete, actionable plan for the development team.

Role	Task	Deliverable(s)
Business Analyst (BA)	1. Create the Feature Issue: Creates a new GitHub Issue for the feature, including the user story and initial acceptance criteria.	A new GitHub Issue (e.g., #123: [Feature] User Invitation).
	2. Create the Feature Branch: Creates a new Git branch from main, named after the Issue (e.g., feature/123-user-invitation).	A new Git branch.
	3. Commit Initial Documents: Adds and commits the Business Requirements Document (BRD) and Use Case files to the new branch.	docs/features/<feature-name>/index.md & use_case.md.
System Architect (SA) / Tech Lead	4. Define Technical Blueprint: Checks out the feature branch and adds or modifies the Technical Requirements Documents (TRDs) to reflect how the new feature will be implemented.	Changes to files in docs/system_spec/ and potentially new Architectural Decision Records (ADRs) in docs/architecture/adrs/.
QA Engineer	5. Define Test Strategy: On the same branch, adds the Test Plan and high-level Test Cases based on the BRD and TRD.	docs/features/<feature-name>/test_plan.md.
SA / Tech Lead	6. Populate the "HOW": Edits the description of the master GitHub Issue (#123) to include a detailed Developer Checklist. This list details every technical task required to complete the feature.	An updated Issue description with a comprehensive checklist.
	7. Plan the Work: Adds the Issue card to the relevant GitHub Project board (e.g., "Q3 Development Sprint") in the To Do column and assigns it to a Developer.	The feature is now visible on the project board and ready for development.

Phase 2: Development & Implementation

This phase focuses on writing the code and updating all related documents as a single, cohesive unit.

Role	Task	Deliverable(s)
Developer	8. Start the Work: Picks up the assigned Issue from the project board. Reads the entire Issue description, including the Developer Checklist, to understand the task.	-
	9. Create a Draft Pull Request: Immediately creates a Draft Pull Request from the feature branch to the main branch. The PR title must reference the Issue (e.g., [WIP] Closes #123: User Invitation).	A Draft Pull Request that links back to the source Issue.
	10. Execute the Checklist: Works through the checklist in the Issue description. This includes: • Writing application code. • Writing unit and integration tests. • Creating database migration scripts. • Updating any TRD or ADR documents as discoveries are made.	Commits of code, tests, and document updates pushed to the feature branch. The PR is continuously updated with these commits.

Phase 3: Review & Collaboration

This phase is a holistic review of all work—documentation and code—by the entire team.

Role	Task	Deliverable(s)
Developer	11. Request Review: Once all checklist items are complete, changes the PR status from "Draft" to "Ready for Review" and requests reviews from the relevant team members (SA, QA, other Developers).	A Pull Request ready for team review.
All Team Members	12. Conduct Holistic Review: Review all changes in the Pull Request's "Files Changed" tab. • SA: Reviews architecture and design. • QA: Reviews testability and test coverage. • BA: Confirms the implementation meets the business requirements. • Peers: Review code quality and standards.	Feedback, questions, and approval submitted as comments and reviews within the Pull Request.

Phase 4: Merge & Deployment

In this final phase, the completed work is integrated and released.

Role	Task	Deliverable(s)
Developer / SA	13. Merge the PR: After receiving approvals, merges the Pull Request into the main branch.	The main branch is now updated with the new feature's code and documentation. The linked Issue (#123) is automatically closed.
DevOps	14. Automated CI/CD to Staging: The merge to main automatically triggers the CI/CD pipeline, which runs all tests and deploys the feature to the Staging environment.	A successful deployment to the staging environment.
QA Engineer	15. Validate on Staging: Performs final User Acceptance Testing (UAT) and regression testing on the staging environment.	A "Go / No-Go" decision for production release. A formal sign-off or test report.
DevOps	16. Deploy to Production: Upon receiving QA sign-off, triggers the deployment pipeline for the Production environment.	The feature is now live for end-users.