Overview

TendSocial uses GitHub Projects (#2) for planning, tracking, and managing development work. This document outlines the workflow for creating issues, implementation plans, and moving work through the project pipeline.

Project Board Structure

GitHub Project #2 has the following columns:

1. Backlog - Unplanned issues and ideas
2. AI Imp Plan Needed - Issues requiring AI-generated implementation plans
3. Review Imp Plan - Implementation plans awaiting approval
4. Ready - Approved and ready for development
5. In Progress - Actively being worked on
6. Done - Completed and verified

Issue Creation Workflow

1. Create Issue

Create GitHub issues for:

• Bugs: Unexpected behavior or errors
• Features: New functionality or enhancements
• Documentation: Doc updates, missing guides
• Technical Debt: Code quality improvements

Issue Template:

## Description
[Clear description of the issue/feature]

## Expected Behavior
[What should happen]

## Current Behavior
[What actually happens - for bugs]

## Steps to Reproduce
[For bugs only]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

2. AI Implementation Planning

For complex features, use the AI agent workflow:

# In conversation with AI agent:
/create_imp_plans

What this does:

1. Analyzes the issue
2. Creates detailed implementation plan
3. Posts plan as issue comment
4. Updates issue status to "Review Imp Plan"

Implementation Plan Format:

• Overview and problem statement
• Proposed changes (file-by-file)
• Verification plan
• Testing strategy

3. Review and Approval

Review the implementation plan in GitHub:

• Comment with feedback/questions
• Request changes if needed
• Move to Ready when approved

4. Development

When starting work:

1. Move issue to In Progress
2. Create feature branch: git checkout -b feature/issue-123-description
3. Implement changes following the plan
4. Commit with references: git commit -m "feat: add feature (#123)"

5. Pull Request

Create PR when ready for review:

• Reference issue in PR description: Closes #123
• Include testing verification
• Request review from team

6. Completion

After PR merge:

1. Move issue to Done
2. Verify deployment
3. Update related documentation

Issue Labels

Use labels for categorization:

Type:

• bug - Something broken
• feature - New functionality
• documentation - Doc updates
• technical-debt - Code quality

Priority:

• high - Critical, blocking
• medium - Important, not blocking
• low - Nice to have

Area:

• api - Backend changes
• app - Frontend changes
• infrastructure - DevOps/deployment
• database - Schema/migrations

Commit Message Convention

Follow Conventional Commits:

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

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• refactor: Code restructuring
• test: Test additions/changes
• chore: Build/tooling changes

Examples:

feat(api): add Vercel AI Gateway integration (#42)
fix(app): resolve plan selection UUID issue (#54)
docs: update database schema for model renames
refactor(api): extract tenant isolation logic

AI Agent Integration

Slash Commands

• /create_imp_plans - Create implementation plans for issues needing them
• /start_todo - Start work on ready issues with approved plans
• /trigger-analytics-sync - Manual analytics sync trigger

Using the AI Agent

For Implementation Planning:

1. Tag issue with "AI Imp Plan Needed" status
2. Run /create_imp_plans in agent conversation
3. AI creates plan and posts to issue
4. Review and approve/request changes

For Implementation:

1. Ensure issue has approved plan in "Ready" status
2. Run /start_todo in agent conversation
3. AI implements following the plan
4. Review PR and verify

Branch Strategy

• main - Production branch, protected
• feature/[issue]-[description] - Feature branches
• fix/[issue]-[description] - Bug fix branches
• docs/[description] - Documentation updates

Review Process

PR Review Checklist:

• [ ] Code follows project conventions
• [ ] Tests pass (pnpm test)
• [ ] Build succeeds (pnpm build)
• [ ] Documentation updated
• [ ] No console errors
• [ ] Breaking changes documented

Related Documentation

• Documentation Standard: Guidelines for writing documentation
• Naming Conventions - Code naming rules