Project Workflow

Guiding Principles

The Plan is the Source of Truth: All work must be tracked in plan.md
The Tech Stack is Deliberate: Changes to the tech stack must be documented in tech-stack.md before implementation
Test-Driven Development: Write unit tests before implementing functionality
High Code Coverage: Aim for >95% code coverage for all modules
User Experience First: Every decision should prioritize user experience
Non-Interactive & CI-Aware: Prefer non-interactive commands. Use CI=true for watch-mode tools (tests, linters) to ensure single execution.

Task Workflow

All tasks follow a strict lifecycle:

Standard Task Workflow

Select Task: Choose the next available task from plan.md in sequential order
Mark In Progress: Before beginning work, edit plan.md and change the task from [ ] to [~]
Write Failing Tests (Red Phase):
- Create a new test file for the feature or bug fix.
- Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task.
- CRITICAL: Run the tests and confirm that they fail as expected. This is the “Red” phase of TDD. Do not proceed until you have failing tests.
Implement to Pass Tests (Green Phase):
- Write the minimum amount of application code necessary to make the failing tests pass.
- Run the test suite again and confirm that all tests now pass. This is the “Green” phase.
Refactor (Optional but Recommended):
- With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior.
- Rerun tests to ensure they still pass after refactoring.
Verify Coverage: Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like:
```
pytest --cov=app --cov-report=html
```
Target: >95% coverage for new code. The specific tools and commands will vary by language and framework.
Document Deviations: If implementation differs from tech stack:
- STOP implementation
- Update tech-stack.md with new design
- Add dated note explaining the change
- Resume implementation
Record Task Summary in Commit Message:
- Stage all code changes related to the task.
- Propose a clear, concise commit message that includes a detailed summary of the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core “why” for the change.
- Example:
```
feat(ui): Create basic HTML structure for calculator

Task: Create UI Structure
Summary: Implemented the basic HTML shell for the tip calculator.
Files: index.html, style.css
Why: Provides the foundational layout for user interaction.
```
Record Task Completion in Plan:
- Read plan.md, find the line for the completed task, and update its status from [~] to [x].
- Write the updated content back to plan.md.

Phase Completion Verification and Checkpointing Protocol

Trigger: This protocol is executed immediately after all tasks in a phase have been marked as [x].

Announce Protocol Start: Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
Ensure Test Coverage for Phase Changes:
- Step 2.1: Determine Phase Scope: To identify the files changed in this phase, you must first find the starting point. Read plan.md to find the Git commit SHA of the previous phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit.
- Step 2.2: List Changed Files: Execute git diff --name-only <previous_checkpoint_sha> HEAD to get a precise list of all files modified during this phase.
- Step 2.3: Verify and Create Tests: For each file in the list:
  - CRITICAL: First, check its extension. Exclude non-code files (e.g., .json, .md, .yaml).
  - For each remaining code file, verify a corresponding test file exists.
  - If a test file is missing, you must create one. Before writing the test, first, analyze other test files in the repository to determine the correct naming convention and testing style. The new tests must validate the functionality described in this phase's tasks (plan.md).
Execute Automated Tests with Proactive Debugging:
- Before execution, you must announce the exact shell command you will use to run the tests.
- Example Announcement: “I will now run the automated test suite to verify the phase. Command: CI=true npm test”
- Execute the announced command.
- If tests fail, you must inform the user and begin debugging. You may attempt to propose a fix a maximum of two times. If the tests still fail after your second proposed fix, you must stop, report the persistent failure, and ask the user for guidance.

Propose a Detailed, Actionable Manual Verification Plan:

CRITICAL: To generate the plan, first analyze product.md, product-guidelines.md, and plan.md to determine the user-facing goals of the completed phase.
You must generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes.

The plan you present to the user must follow this format:

For a Frontend Change:

The automated tests have passed. For manual verification, please follow these steps:

**Manual Verification Steps:**
1.  **Start the development server with the command:** `npm run dev`
2.  **Open your browser to:** `http://localhost:3000`
3.  **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly.

For a Backend Change:

The automated tests have passed. For manual verification, please follow these steps:

**Manual Verification Steps:**
1.  **Ensure the server is running.**
2.  **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'`
3.  **Confirm that you receive:** A JSON response with a status of `201 Created`.

Await Explicit User Feedback:
- After presenting the detailed plan, ask the user for confirmation: “Does this meet your expectations? Please confirm with yes or provide feedback on what needs to be changed.”
- PAUSE and await the user's response. Do not proceed without an explicit yes or confirmation.
Create Checkpoint Commit:
- Stage all code and plan changes.
- Perform the commit with a clear and concise message including the phase name (e.g., conductor(checkpoint): Phase Complete: User Authentication Flow).
Get and Record Phase Checkpoint SHA:
- Step 7.1: Get Commit Hash: Obtain the hash of the just-created checkpoint commit (git log -1 --format="%H").
- Step 7.2: Update Plan: Read plan.md, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format [checkpoint: <sha>].
- Step 7.3: Write Plan: Write the updated content back to plan.md.
Commit Plan Update:
- Action: Stage the modified plan.md file.
- Action: Commit this change with a descriptive message following the format conductor(plan): Mark phase '<PHASE NAME>' as complete.
Announce Completion: Inform the user that the phase is complete and the checkpoint has been created.

Quality Gates

Before marking any task complete, verify:

[ ] All tests pass
[ ] Code coverage meets requirements (>95%)
[ ] Code follows project's code style guidelines (as defined in code_styleguides/)
[ ] All public functions/methods are documented (e.g., docstrings, JSDoc, GoDoc)
[ ] Type safety is enforced (e.g., type hints, TypeScript types, Go types)
[ ] No linting or static analysis errors (using the project's configured tools)
[ ] Works correctly on mobile (if applicable)
[ ] Documentation updated if needed
[ ] No security vulnerabilities introduced

Development Commands

AI AGENT INSTRUCTION: This section should be adapted to the project's specific language, framework, and build tools.

Setup

# Example: Commands to set up the development environment (e.g., install dependencies, configure database)
# e.g., for a Node.js project: npm install
# e.g., for a Go project: go mod tidy

Daily Development

# Example: Commands for common daily tasks (e.g., start dev server, run tests, lint, format)
# e.g., for a Node.js project: npm run dev, npm test, npm run lint
# e.g., for a Go project: go run main.go, go test ./..., go fmt ./...

Before Committing

# Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests)
# e.g., for a Node.js project: npm run check
# e.g., for a Go project: make check (if a Makefile exists)

Testing Requirements

Unit Testing

Every module must have corresponding tests.
Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach).
Mock external dependencies.
Test both success and failure cases.

Integration Testing

Test complete user flows
Verify database transactions
Test authentication and authorization
Check form submissions

Mobile Testing

Test on actual iPhone when possible
Use Safari developer tools
Test touch interactions
Verify responsive layouts
Check performance on 3G/4G

Code Review Process

Self-Review Checklist

Before requesting review:

Functionality
- Feature works as specified
- Edge cases handled
- Error messages are user-friendly
Code Quality
- Follows style guide
- DRY principle applied
- Clear variable/function names
- Appropriate comments
Testing
- Unit tests comprehensive
- Integration tests pass
- Coverage adequate (>95%)
Security
- No hardcoded secrets
- Input validation present
- SQL injection prevented
- XSS protection in place
Performance
- Database queries optimized
- Images optimized
- Caching implemented where needed
Mobile Experience
- Touch targets adequate (44x44px)
- Text readable without zooming
- Performance acceptable on mobile
- Interactions feel native

Commit Guidelines

Message Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

feat: New feature
fix: Bug fix
docs: Documentation only
style: Formatting, missing semicolons, etc.
refactor: Code change that neither fixes a bug nor adds a feature
test: Adding missing tests
chore: Maintenance tasks

Examples

git commit -m "feat(auth): Add remember me functionality"
git commit -m "fix(posts): Correct excerpt generation for short posts"
git commit -m "test(comments): Add tests for emoji reaction limits"
git commit -m "style(mobile): Improve button touch targets"

Definition of Done

A task is complete when:

All code implemented to specification
Unit tests written and passing
Code coverage meets project requirements
Documentation complete (if applicable)
Code passes all configured linting and static analysis checks
Works beautifully on mobile (if applicable)
Implementation notes added to plan.md
Changes committed with proper message
Git note with task summary attached to the commit

Emergency Procedures

Critical Bug in Production

Create hotfix branch from main
Write failing test for bug
Implement minimal fix
Test thoroughly including mobile
Deploy immediately
Document in plan.md

Data Loss

Stop all write operations
Restore from latest backup
Verify data integrity
Document incident
Update backup procedures

Security Breach

Rotate all secrets immediately
Review access logs
Patch vulnerability
Notify affected users (if any)
Document and update security procedures

Deployment Workflow

Pre-Deployment Checklist

[ ] All tests passing
[ ] Coverage >95%
[ ] No linting errors
[ ] Mobile testing complete
[ ] Environment variables configured
[ ] Database migrations ready
[ ] Backup created

Deployment Steps

Merge feature branch to main
Tag release with version
Push to deployment service
Run database migrations
Verify deployment
Test critical paths
Monitor for errors

Post-Deployment

Monitor analytics
Check error logs
Gather user feedback
Plan next iteration

Continuous Improvement

Review workflow weekly
Update based on pain points
Document lessons learned
Optimize for user happiness
Keep things simple and maintainable