From baad41da9882e5d5b475be4fc9706197c5b3d6db Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 28 Jan 2026 14:24:08 -0500 Subject: [PATCH] feat(plugins): implement Sprint 5 documentation and fixes (#266-#269) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Release v5.2.0 Documentation: - Add git-flow branching strategy guide (docs/BRANCHING-STRATEGY.md) - Add clarity-assist ND support documentation (docs/ND-SUPPORT.md) - Update DEBUGGING-CHECKLIST.md with Gitea auto-close behavior and MCP restart notes - Update plugin READMEs to reference new documentation Bug Fix: - Add milestone parameter to update_issue MCP tool (gitea_client.py, server.py, tools/issues.py) Version Updates: - Marketplace version: 5.1.0 → 5.2.0 - README title: v5.1.0 → v5.2.0 - CHANGELOG: [Unreleased] → [5.2.0] - 2026-01-28 Closes #266, Closes #267, Closes #268, Closes #269 Co-Authored-By: Claude Opus 4.5 --- .claude-plugin/marketplace.json | 2 +- CHANGELOG.md | 22 +- README.md | 2 +- docs/DEBUGGING-CHECKLIST.md | 43 +- mcp-servers/gitea/mcp_server/gitea_client.py | 19 +- mcp-servers/gitea/mcp_server/server.py | 4 + mcp-servers/gitea/mcp_server/tools/issues.py | 4 +- plugins/clarity-assist/README.md | 4 + plugins/clarity-assist/docs/ND-SUPPORT.md | 328 +++++++++++ plugins/git-flow/README.md | 4 + plugins/git-flow/docs/BRANCHING-STRATEGY.md | 541 +++++++++++++++++++ 11 files changed, 967 insertions(+), 6 deletions(-) create mode 100644 plugins/clarity-assist/docs/ND-SUPPORT.md create mode 100644 plugins/git-flow/docs/BRANCHING-STRATEGY.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1e643d9..28a5f18 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "metadata": { "description": "Project management plugins with Gitea and NetBox integrations", - "version": "5.1.0" + "version": "5.2.0" }, "plugins": [ { diff --git a/CHANGELOG.md b/CHANGELOG.md index d934e13..47fc12e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,10 +4,29 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). -## [Unreleased] +## [5.2.0] - 2026-01-28 ### Added +#### Sprint 5: Documentation (V5.2.0 Plugin Enhancements) +Documentation and guides for the plugin enhancements initiative. + +**git-flow v1.2.0:** +- **Branching Strategy Guide** (`docs/BRANCHING-STRATEGY.md`) - Complete documentation of `development -> staging -> main` promotion flow with Mermaid diagrams + +**clarity-assist v1.2.0:** +- **ND Support Guide** (`docs/ND-SUPPORT.md`) - Documentation of neurodivergent accommodations, features, and usage examples + +**Gitea MCP Server:** +- **`update_issue` milestone parameter** - Can now assign/change milestones programmatically + +**Sprint Completed:** +- Milestone: Sprint 5 - Documentation (closed 2026-01-28) +- Issues: #266, #267, #268, #269 +- Wiki: [Change V5.2.0: Plugin Enhancements (Sprint 5 Documentation)](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0%3A-Plugin-Enhancements-%28Sprint-5-Documentation%29) + +--- + #### Sprint 4: Commands (V5.2.0 Plugin Enhancements) Implementation of 18 new user-facing commands across 8 plugins. @@ -55,6 +74,7 @@ Implementation of 18 new user-facing commands across 8 plugins. ### Fixed - **MCP:** Project directory detection - all run.sh scripts now capture `CLAUDE_PROJECT_DIR` from PWD before changing directories +- **Docs:** Added Gitea auto-close behavior and MCP session restart notes to DEBUGGING-CHECKLIST.md --- diff --git a/README.md b/README.md index 739554d..3f1e3ea 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Leo Claude Marketplace - v5.1.0 +# Leo Claude Marketplace - v5.2.0 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows. diff --git a/docs/DEBUGGING-CHECKLIST.md b/docs/DEBUGGING-CHECKLIST.md index f9146b9..04b7c52 100644 --- a/docs/DEBUGGING-CHECKLIST.md +++ b/docs/DEBUGGING-CHECKLIST.md @@ -2,7 +2,7 @@ **Purpose:** Systematic approach to diagnose and fix plugin loading issues. -Last Updated: 2026-01-22 +Last Updated: 2026-01-28 --- @@ -186,6 +186,47 @@ echo -e "\n=== Config Files ===" | Wrong path edits | Changes don't take effect | Edit installed path or reinstall after source changes | | Missing credentials | MCP connection errors | Create `~/.config/claude/gitea.env` with API credentials | | Invalid hook events | Hooks don't fire | Use only valid event names (see Step 7) | +| Gitea issues not closing | Merged to non-default branch | Manually close issues (see below) | +| MCP changes not taking effect | Session caching | Restart Claude Code session (see below) | + +### Gitea Auto-Close Behavior + +**Issue:** Using `Closes #XX` or `Fixes #XX` in commit/PR messages does NOT auto-close issues when merging to `development`. + +**Root Cause:** Gitea only auto-closes issues when merging to the **default branch** (typically `main` or `master`). Merging to `development`, `staging`, or any other branch will NOT trigger auto-close. + +**Workaround:** +1. Use the Gitea MCP tool to manually close issues after merging to development: + ``` + mcp__plugin_projman_gitea__update_issue(issue_number=XX, state="closed") + ``` +2. Or close issues via the Gitea web UI +3. The auto-close keywords will still work when the changes are eventually merged to `main` + +**Recommendation:** Include the `Closes #XX` keywords in commits anyway - they'll work when the final merge to `main` happens. + +### MCP Session Restart Requirement + +**Issue:** Changes to MCP servers, hooks, or plugin configuration don't take effect immediately. + +**Root Cause:** Claude Code loads MCP tools and plugin configuration at session start. These are cached in session memory and not reloaded dynamically. + +**What requires a session restart:** +- MCP server code changes (Python files in `mcp-servers/`) +- Changes to `.mcp.json` files +- Changes to `hooks/hooks.json` +- Changes to `plugin.json` +- Adding new MCP tools or modifying tool signatures + +**What does NOT require a restart:** +- Command/skill markdown files (`.md`) - these are read on invocation +- Agent markdown files - read when agent is invoked + +**Correct workflow after plugin changes:** +1. Make changes to source files +2. Run `./scripts/verify-hooks.sh` to validate +3. Inform user: "Please restart Claude Code for changes to take effect" +4. **Do NOT clear cache mid-session** - see "Cache Clearing" section --- diff --git a/mcp-servers/gitea/mcp_server/gitea_client.py b/mcp-servers/gitea/mcp_server/gitea_client.py index 638fda2..a5e3449 100644 --- a/mcp-servers/gitea/mcp_server/gitea_client.py +++ b/mcp-servers/gitea/mcp_server/gitea_client.py @@ -135,9 +135,24 @@ class GiteaClient: body: Optional[str] = None, state: Optional[str] = None, labels: Optional[List[str]] = None, + milestone: Optional[int] = None, repo: Optional[str] = None ) -> Dict: - """Update existing issue. Repo must be 'owner/repo' format.""" + """ + Update existing issue. + + Args: + issue_number: Issue number to update + title: New title (optional) + body: New body (optional) + state: New state - 'open' or 'closed' (optional) + labels: New labels (optional) + milestone: Milestone ID to assign (optional) + repo: Repository in 'owner/repo' format + + Returns: + Updated issue dictionary + """ owner, target_repo = self._parse_repo(repo) url = f"{self.base_url}/repos/{owner}/{target_repo}/issues/{issue_number}" data = {} @@ -149,6 +164,8 @@ class GiteaClient: data['state'] = state if labels is not None: data['labels'] = labels + if milestone is not None: + data['milestone'] = milestone logger.info(f"Updating issue #{issue_number} in {owner}/{target_repo}") response = self.session.patch(url, json=data) response.raise_for_status() diff --git a/mcp-servers/gitea/mcp_server/server.py b/mcp-servers/gitea/mcp_server/server.py index b5e53a7..0630c6a 100644 --- a/mcp-servers/gitea/mcp_server/server.py +++ b/mcp-servers/gitea/mcp_server/server.py @@ -168,6 +168,10 @@ class GiteaMCPServer: "items": {"type": "string"}, "description": "New labels" }, + "milestone": { + "type": "integer", + "description": "Milestone ID to assign" + }, "repo": { "type": "string", "description": "Repository name (for PMO mode)" diff --git a/mcp-servers/gitea/mcp_server/tools/issues.py b/mcp-servers/gitea/mcp_server/tools/issues.py index bf759f1..c0ae3dc 100644 --- a/mcp-servers/gitea/mcp_server/tools/issues.py +++ b/mcp-servers/gitea/mcp_server/tools/issues.py @@ -200,6 +200,7 @@ class IssueTools: body: Optional[str] = None, state: Optional[str] = None, labels: Optional[List[str]] = None, + milestone: Optional[int] = None, repo: Optional[str] = None ) -> Dict: """ @@ -211,6 +212,7 @@ class IssueTools: body: New body (optional) state: New state - 'open' or 'closed' (optional) labels: New labels (optional) + milestone: Milestone ID to assign (optional) repo: Override configured repo (for PMO multi-repo) Returns: @@ -229,7 +231,7 @@ class IssueTools: loop = asyncio.get_event_loop() return await loop.run_in_executor( None, - lambda: self.gitea.update_issue(issue_number, title, body, state, labels, repo) + lambda: self.gitea.update_issue(issue_number, title, body, state, labels, milestone, repo) ) async def add_comment( diff --git a/plugins/clarity-assist/README.md b/plugins/clarity-assist/README.md index e47f4a7..f64d6be 100644 --- a/plugins/clarity-assist/README.md +++ b/plugins/clarity-assist/README.md @@ -90,6 +90,10 @@ After clarification, you receive a structured specification: [List of assumptions] ``` +## Documentation + +- [Neurodivergent Support Guide](docs/ND-SUPPORT.md) - How clarity-assist supports ND users with executive function challenges and cognitive differences + ## Integration For CLAUDE.md integration instructions, see `claude-md-integration.md`. diff --git a/plugins/clarity-assist/docs/ND-SUPPORT.md b/plugins/clarity-assist/docs/ND-SUPPORT.md new file mode 100644 index 0000000..11f4b6c --- /dev/null +++ b/plugins/clarity-assist/docs/ND-SUPPORT.md @@ -0,0 +1,328 @@ +# Neurodivergent Support in clarity-assist + +This document describes how clarity-assist is designed to support users with neurodivergent traits, including ADHD, autism, anxiety, and other conditions that affect executive function, sensory processing, or cognitive style. + +## Overview + +### Purpose + +clarity-assist exists to help all users transform vague or incomplete requests into clear, actionable specifications. For neurodivergent users specifically, it addresses common challenges: + +- **Executive function difficulties** - Breaking down complex tasks, getting started, managing scope +- **Working memory limitations** - Keeping track of context across long conversations +- **Decision fatigue** - Facing too many open-ended choices +- **Processing style differences** - Preferring structured, predictable interactions +- **Anxiety around uncertainty** - Needing clear expectations and explicit confirmation + +### Philosophy + +Our design philosophy centers on three principles: + +1. **Reduce cognitive load** - Never force the user to hold too much in their head at once +2. **Provide structure** - Use consistent, predictable patterns for all interactions +3. **Respect different communication styles** - Accommodate rather than assume one "right" way to think + +## Features for ND Users + +### 1. Reduced Cognitive Load + +**Prompt Simplification** +- The 4-D methodology (Deconstruct, Diagnose, Develop, Deliver) breaks down complex requests into manageable phases +- Users never need to specify everything upfront - clarification happens incrementally + +**Task Breakdown** +- Large requests are decomposed into explicit components +- Dependencies and relationships are surfaced rather than left implicit +- Scope boundaries are clearly defined (in-scope vs. out-of-scope) + +### 2. Structured Output + +**Consistent Formatting** +- Every clarification session produces the same structured specification: + - Summary (1-2 sentences) + - Scope (In/Out) + - Requirements table (numbered, prioritized) + - Assumptions list +- This predictability reduces the mental effort of parsing responses + +**Predictable Patterns** +- Questions always follow the same format +- Progress summaries appear at regular intervals +- Escalation (simple to complex) is always offered, never forced + +**Bulleted Lists Over Prose** +- Requirements are presented as scannable lists, not paragraphs +- Options are numbered for easy reference +- Key information is highlighted with bold labels + +### 3. Customizable Verbosity + +**Detail Levels** +- `/clarify` - Full methodology for complex requests (more thorough, more questions) +- `/quick-clarify` - Rapid mode for simple disambiguation (fewer questions, faster) + +**User Control** +- Users can always say "that's enough detail" to end questioning early +- The plugin offers to break sessions into smaller parts +- "Good enough for now" is explicitly validated as an acceptable outcome + +### 4. Vagueness Detection + +The `UserPromptSubmit` hook automatically detects prompts that might benefit from clarification and gently suggests using `/clarify`. + +**Detection Signals** +- Short prompts (< 10 words) without specific technical terms +- Vague action phrases: "help me", "fix this", "make it better" +- Ambiguous scope words: "somehow", "something", "stuff", "etc." +- Open questions without context + +**Non-Blocking Approach** +- The hook never prevents you from proceeding +- It provides a suggestion with a vagueness score (percentage) +- You can disable auto-suggestions entirely via environment variable + +### 5. Focus Aids + +**Task Prioritization** +- Requirements are tagged as Must/Should/Could/Won't (MoSCoW) +- Critical items are separated from nice-to-haves +- Scope creep is explicitly called out and deferred + +**Context Switching Warnings** +- When questions touch multiple areas, the plugin acknowledges the complexity +- Offers to focus on one aspect at a time +- Summarizes frequently to rebuild context after interruptions + +## How It Works + +### The UserPromptSubmit Hook + +When you submit a prompt, the vagueness detection hook (`hooks/vagueness-check.sh`) runs automatically: + +``` +User submits prompt + | + v +Hook reads prompt from stdin + | + v +Skip if: empty, starts with /, or contains file paths + | + v +Calculate vagueness score (0.0 - 1.0) + - Short prompts: +0.3 + - Vague action phrases: +0.2 + - Ambiguous scope words: +0.15 + - Missing technical specifics: +0.2 + - Short questions without context: +0.15 + | + v +If score >= threshold (default 0.6): + - Output gentle suggestion with [clarity-assist] prefix + - Show vagueness percentage + | + v +Exit 0 (always non-blocking) +``` + +### Example Hook Output + +``` +[clarity-assist] Your prompt could benefit from more clarity. +[clarity-assist] Consider running /clarity-assist to refine your request. +[clarity-assist] (Vagueness score: 65% - this is a suggestion, not a block) +``` + +### The 4-D Methodology + +| Phase | What Happens | ND Benefit | +|-------|--------------|------------| +| **Deconstruct** | Break request into components | Shows the full picture without overwhelming | +| **Diagnose** | Identify gaps and conflicts | Surfaces hidden assumptions | +| **Develop** | Ask structured questions | Option-based, chunked, contextual | +| **Deliver** | Produce specification | Consistent, scannable format | + +## Usage Examples + +### Before: Vague Request + +``` +User: Make the app faster +``` + +This triggers vagueness detection because: +- Short (4 words) +- Vague action ("make") +- No specific technical context +- No measurable outcome + +### After: Clarified with /clarify + +``` +User: /clarify Make the app faster + +Claude: Let me help clarify what kind of performance improvements you're looking for. + +**What type of slowness are you experiencing?** +1. Initial page load takes too long +2. Interactions feel sluggish (clicking, typing) +3. API calls are slow +4. All of the above +5. Other + +[I'm asking because each has very different solutions] +``` + +``` +User: 1 + +Claude: Initial page load - got it. + +**What's an acceptable load time for you?** +1. Under 1 second (aggressive) +2. Under 2 seconds (standard) +3. Under 3 seconds (relaxed) +4. I don't have a specific target + +[This helps me know whether to suggest quick wins or a major optimization effort] +``` + +After 2-3 more questions, the user receives: + +```markdown +## Clarified Request + +### Summary +Optimize initial page load time to under 2 seconds by addressing bundle size and initial render blocking resources. + +### Scope +**In Scope:** +- Bundle analysis and splitting +- Lazy loading non-critical components +- Image optimization +- CSS/JS minification check + +**Out of Scope:** +- Backend API optimization +- Database query performance +- CDN setup + +### Requirements +| # | Requirement | Priority | Notes | +|---|-------------|----------|-------| +| 1 | Page loads in < 2s on 4G | Must | Measured via Lighthouse | +| 2 | Largest contentful paint < 1.5s | Should | Core Web Vital | +| 3 | No layout shift after load | Should | CLS < 0.1 | + +### Assumptions +- Current load time is > 3 seconds (based on "too long" description) +- Target browsers: modern evergreen (Chrome, Firefox, Safari) +- Build tooling already configured (webpack/vite) +``` + +### Common Patterns Detected + +| Pattern | Example | What It Triggers | +|---------|---------|------------------| +| Missing context | "Fix the bug" | "Which bug? In which file or feature?" | +| Ambiguous scope | "Update the user stuff" | "What specifically needs updating?" | +| Unclear goals | "Make it better" | "Better in what way? Faster? Cleaner? More features?" | +| Implicit knowledge | "Do it like last time" | "I don't have context from previous sessions" | +| Conflicting requests | "Keep it simple but add everything" | "Which matters more: simplicity or completeness?" | + +### Quick-Clarify Example + +For simpler requests that just need minor disambiguation: + +``` +User: /quick-clarify Add a delete button to the user list + +Claude: I'll add a delete button to each row in the user list. + +**Should deletion require confirmation?** +1. Yes - show confirmation dialog (Recommended) +2. No - delete immediately +3. Soft delete - mark as deleted but keep data + +[Asking because accidental deletions can be problematic] +``` + +``` +User: 1 + +Claude: Got it. I'll implement a delete button with confirmation dialog. Starting now. +``` + +## Configuration Options + +### Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `CLARITY_ASSIST_AUTO_SUGGEST` | `true` | Enable/disable automatic vagueness detection | +| `CLARITY_ASSIST_VAGUENESS_THRESHOLD` | `0.6` | Score threshold to trigger suggestion (0.0-1.0) | + +### Disabling Auto-Suggestions + +If you find the vagueness detection unhelpful, disable it in your shell profile or `.env`: + +```bash +export CLARITY_ASSIST_AUTO_SUGGEST=false +``` + +### Adjusting Sensitivity + +To make detection more or less sensitive: + +```bash +# More sensitive (suggests more often) +export CLARITY_ASSIST_VAGUENESS_THRESHOLD=0.4 + +# Less sensitive (only very vague prompts) +export CLARITY_ASSIST_VAGUENESS_THRESHOLD=0.8 +``` + +## Tips for ND Users + +### If You're Feeling Overwhelmed + +- Use `/quick-clarify` instead of `/clarify` for faster interactions +- Say "let's focus on just one thing" to narrow scope +- Ask to "pause and summarize" at any point +- It's OK to say "I don't know" - the plugin will offer concrete alternatives + +### If You Have Executive Function Challenges + +- Start with `/clarify` even for tasks you think are simple - it helps with planning +- The structured specification can serve as a checklist +- Use the scope boundaries to prevent scope creep + +### If You Prefer Detailed Structure + +- The 4-D methodology provides a predictable framework +- All output follows consistent formatting +- Questions always offer numbered options + +### If You Have Anxiety About Getting It Right + +- The plugin validates "good enough for now" as acceptable +- You can always revisit and change earlier answers +- Assumptions are explicitly listed - nothing is hidden + +## Accessibility Notes + +- All output uses standard markdown that works with screen readers +- No time pressure - take as long as you need between responses +- Questions are designed to be answerable without deep context retrieval +- Visual patterns (bold, bullets, tables) create scannable structure + +## Feedback + +If you have suggestions for improving neurodivergent support in clarity-assist, please open an issue at: + +https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/issues + +Include the label `clarity-assist` and describe: +- What challenge you faced +- What would have helped +- Any specific accommodations you'd like to see diff --git a/plugins/git-flow/README.md b/plugins/git-flow/README.md index 1de8bb6..2121bed 100644 --- a/plugins/git-flow/README.md +++ b/plugins/git-flow/README.md @@ -119,6 +119,10 @@ The git-assistant agent helps resolve merge conflicts with analysis and recommen → Status: Clean, up-to-date ``` +## Documentation + +- [Branching Strategy Guide](docs/BRANCHING-STRATEGY.md) - Detailed documentation of the `development -> staging -> main` promotion flow + ## Integration For CLAUDE.md integration instructions, see `claude-md-integration.md`. diff --git a/plugins/git-flow/docs/BRANCHING-STRATEGY.md b/plugins/git-flow/docs/BRANCHING-STRATEGY.md new file mode 100644 index 0000000..b582c6b --- /dev/null +++ b/plugins/git-flow/docs/BRANCHING-STRATEGY.md @@ -0,0 +1,541 @@ +# Branching Strategy + +## Overview + +This document defines the branching strategy used by git-flow to manage code changes across environments. The strategy ensures: + +- **Stability**: Production code is always release-ready +- **Isolation**: Features are developed in isolation without affecting others +- **Traceability**: Clear history of what changed and when +- **Collaboration**: Multiple developers can work simultaneously without conflicts + +The strategy follows a hierarchical promotion model: feature branches merge into development, which promotes to staging for testing, and finally to main for production release. + +## Branch Types + +### Main Branches + +| Branch | Purpose | Stability | Direct Commits | +|--------|---------|-----------|----------------| +| `main` | Production releases | Highest | Never | +| `staging` | Pre-production testing | High | Never | +| `development` | Active development | Medium | Never | + +### Feature Branches + +Feature branches are short-lived branches created from `development` for implementing specific changes. + +| Prefix | Purpose | Example | +|--------|---------|---------| +| `feat/` | New features | `feat/user-authentication` | +| `fix/` | Bug fixes | `fix/login-timeout-error` | +| `docs/` | Documentation only | `docs/api-reference` | +| `refactor/` | Code restructuring | `refactor/auth-module` | +| `test/` | Test additions/fixes | `test/auth-coverage` | +| `chore/` | Maintenance tasks | `chore/update-dependencies` | + +### Special Branches + +| Branch | Purpose | Created From | Merges Into | +|--------|---------|--------------|-------------| +| `hotfix/*` | Emergency production fixes | `main` | `main` AND `development` | +| `release/*` | Release preparation | `development` | `staging` then `main` | + +## Branch Hierarchy + +``` + PRODUCTION + │ + ▼ + ┌───────────────[ main ]───────────────┐ + │ (stable releases) │ + │ ▲ │ + │ │ PR │ + │ │ │ + │ ┌───────┴───────┐ │ + │ │ staging │ │ + │ │ (testing) │ │ + │ └───────▲───────┘ │ + │ │ PR │ + │ │ │ + │ ┌─────────┴─────────┐ │ + │ │ development │ │ + │ │ (integration) │ │ + │ └─────────▲─────────┘ │ + │ ╱ │ ╲ │ + │ PR╱ │PR ╲PR │ + │ ╱ │ ╲ │ + │ ┌─────┴──┐ ┌──┴───┐ ┌┴─────┐ │ + │ │ feat/* │ │ fix/*│ │docs/*│ │ + │ └────────┘ └──────┘ └──────┘ │ + │ FEATURE BRANCHES │ + └───────────────────────────────────────┘ +``` + +## Workflow + +### Feature Development + +The standard workflow for implementing a new feature or fix: + +```mermaid +gitGraph + commit id: "initial" + branch development + checkout development + commit id: "dev-base" + branch feat/new-feature + checkout feat/new-feature + commit id: "implement" + commit id: "tests" + commit id: "polish" + checkout development + merge feat/new-feature id: "PR merged" + commit id: "other-work" +``` + +**Steps:** + +1. **Create branch from development** + ```bash + git checkout development + git pull origin development + git checkout -b feat/add-user-auth + ``` + Or use git-flow command: + ``` + /branch-start add user authentication + ``` + +2. **Implement changes** + - Make commits following conventional commit format + - Keep commits atomic and focused + - Push regularly to remote + +3. **Create Pull Request** + - Target: `development` + - Include description of changes + - Link related issues + +4. **Review and merge** + - Address review feedback + - Squash or rebase as needed + - Merge when approved + +5. **Cleanup** + - Delete feature branch after merge + ``` + /branch-cleanup + ``` + +### Release Promotion + +Promoting code from development to production: + +```mermaid +gitGraph + commit id: "v1.0.0" tag: "v1.0.0" + branch development + checkout development + commit id: "feat-1" + commit id: "feat-2" + commit id: "fix-1" + branch staging + checkout staging + commit id: "staging-test" + checkout main + merge staging id: "v1.1.0" tag: "v1.1.0" + checkout development + merge main id: "sync" +``` + +**Steps:** + +1. **Prepare release** + - Ensure development is stable + - Update version numbers + - Update CHANGELOG.md + +2. **Promote to staging** + ```bash + git checkout staging + git merge development + git push origin staging + ``` + +3. **Test in staging** + - Run integration tests + - Perform QA validation + - Fix any issues (merge fixes to development first, then re-promote) + +4. **Promote to main** + ```bash + git checkout main + git merge staging + git tag -a v1.1.0 -m "Release v1.1.0" + git push origin main --tags + ``` + +5. **Sync development** + ```bash + git checkout development + git merge main + git push origin development + ``` + +### Hotfix Handling + +Emergency fixes for production issues: + +```mermaid +gitGraph + commit id: "v1.0.0" tag: "v1.0.0" + branch development + checkout development + commit id: "ongoing-work" + checkout main + branch hotfix/critical-bug + checkout hotfix/critical-bug + commit id: "fix" + checkout main + merge hotfix/critical-bug id: "v1.0.1" tag: "v1.0.1" + checkout development + merge main id: "sync-fix" +``` + +**Steps:** + +1. **Create hotfix branch from main** + ```bash + git checkout main + git pull origin main + git checkout -b hotfix/critical-security-fix + ``` + +2. **Implement fix** + - Minimal, focused changes only + - Include tests for the fix + - Follow conventional commit format + +3. **Merge to main** + ```bash + git checkout main + git merge hotfix/critical-security-fix + git tag -a v1.0.1 -m "Hotfix: critical security fix" + git push origin main --tags + ``` + +4. **Merge to development** (critical step) + ```bash + git checkout development + git merge main + git push origin development + ``` + +5. **Delete hotfix branch** + ```bash + git branch -d hotfix/critical-security-fix + git push origin --delete hotfix/critical-security-fix + ``` + +## PR Requirements + +### To development + +| Requirement | Description | +|-------------|-------------| +| Passing tests | All CI tests must pass | +| Conventional commit | Message follows `type(scope): description` format | +| No conflicts | Branch must be rebased on latest development | +| Code review | At least one approval (recommended) | + +### To staging + +| Requirement | Description | +|-------------|-------------| +| All checks pass | CI, linting, tests, security scans | +| From development | Only PRs from development branch | +| Clean history | Squashed or rebased commits | +| Release notes | CHANGELOG updated with version | + +### To main (Protected) + +| Requirement | Description | +|-------------|-------------| +| Source restriction | PRs only from `staging` or `development` | +| All checks pass | Complete CI pipeline success | +| Approvals | Minimum 1-2 reviewer approvals | +| No direct push | Force push disabled | +| Version tag | Must include version tag on merge | + +## Branch Flow Diagram + +### Complete Lifecycle + +```mermaid +flowchart TD + subgraph Feature["Feature Development"] + A[Create feature branch] --> B[Implement changes] + B --> C[Push commits] + C --> D[Create PR to development] + D --> E{Review passed?} + E -->|No| B + E -->|Yes| F[Merge to development] + F --> G[Delete feature branch] + end + + subgraph Release["Release Cycle"] + H[development stable] --> I[Create PR to staging] + I --> J[Test in staging] + J --> K{Tests passed?} + K -->|No| L[Fix in development] + L --> H + K -->|Yes| M[Create PR to main] + M --> N[Tag release] + N --> O[Sync development] + end + + subgraph Hotfix["Hotfix Process"] + P[Critical bug in prod] --> Q[Create hotfix from main] + Q --> R[Implement fix] + R --> S[Merge to main + tag] + S --> T[Merge to development] + end + + G --> H + O --> Feature + T --> Feature +``` + +### Release Cycle Timeline + +```mermaid +gantt + title Release Cycle + dateFormat YYYY-MM-DD + section Feature Development + Feature A :a1, 2024-01-01, 5d + Feature B :a2, 2024-01-03, 4d + Bug Fix :a3, 2024-01-06, 2d + section Integration + Merge to development:b1, after a1, 1d + Integration testing :b2, after b1, 2d + section Release + Promote to staging :c1, after b2, 1d + QA testing :c2, after c1, 3d + Release to main :milestone, after c2, 0d +``` + +## Examples + +### Example 1: Adding a New Feature + +**Scenario:** Add user password reset functionality + +```bash +# 1. Start from development +git checkout development +git pull origin development + +# 2. Create feature branch +git checkout -b feat/password-reset + +# 3. Make changes and commit +git add src/auth/password-reset.ts +git commit -m "feat(auth): add password reset request handler" + +git add src/email/templates/reset-email.html +git commit -m "feat(email): add password reset email template" + +git add tests/auth/password-reset.test.ts +git commit -m "test(auth): add password reset tests" + +# 4. Push and create PR +git push -u origin feat/password-reset +# Create PR targeting development + +# 5. After merge, cleanup +git checkout development +git pull origin development +git branch -d feat/password-reset +``` + +### Example 2: Bug Fix + +**Scenario:** Fix login timeout issue + +```bash +# 1. Create fix branch +git checkout development +git pull origin development +git checkout -b fix/login-timeout + +# 2. Fix and commit +git add src/auth/session.ts +git commit -m "fix(auth): increase session timeout to 30 minutes + +The default 5-minute timeout was causing frequent re-authentication. +Extended to 30 minutes based on user feedback. + +Closes #456" + +# 3. Push and create PR +git push -u origin fix/login-timeout +``` + +### Example 3: Documentation Update + +**Scenario:** Update API documentation + +```bash +# 1. Create docs branch +git checkout development +git checkout -b docs/api-authentication + +# 2. Update docs +git add docs/api/authentication.md +git commit -m "docs(api): document authentication endpoints + +Add detailed documentation for: +- POST /auth/login +- POST /auth/logout +- POST /auth/refresh +- GET /auth/me" + +# 3. Push and create PR +git push -u origin docs/api-authentication +``` + +### Example 4: Emergency Hotfix + +**Scenario:** Critical security vulnerability in production + +```bash +# 1. Create hotfix from main +git checkout main +git pull origin main +git checkout -b hotfix/sql-injection + +# 2. Fix the issue +git add src/db/queries.ts +git commit -m "fix(security): sanitize SQL query parameters + +CRITICAL: Addresses SQL injection vulnerability in user search. +All user inputs are now properly parameterized. + +CVE: CVE-2024-XXXXX" + +# 3. Merge to main with tag +git checkout main +git merge hotfix/sql-injection +git tag -a v2.1.1 -m "Hotfix: SQL injection vulnerability" +git push origin main --tags + +# 4. Sync to development (IMPORTANT!) +git checkout development +git merge main +git push origin development + +# 5. Cleanup +git branch -d hotfix/sql-injection +``` + +### Example 5: Release Promotion + +**Scenario:** Release version 2.2.0 + +```bash +# 1. Ensure development is ready +git checkout development +git pull origin development +# Run full test suite +npm test + +# 2. Update version and changelog +# Edit package.json, CHANGELOG.md +git add package.json CHANGELOG.md +git commit -m "chore(release): prepare v2.2.0" + +# 3. Promote to staging +git checkout staging +git merge development +git push origin staging + +# 4. After QA approval, promote to main +git checkout main +git merge staging +git tag -a v2.2.0 -m "Release v2.2.0" +git push origin main --tags + +# 5. Sync development +git checkout development +git merge main +git push origin development +``` + +## Configuration + +### Environment Variables + +Configure the branching strategy via environment variables: + +```bash +# Default base branch for new features +GIT_DEFAULT_BASE=development + +# Protected branches (comma-separated) +GIT_PROTECTED_BRANCHES=main,master,development,staging,production + +# Workflow style +GIT_WORKFLOW_STYLE=feature-branch + +# Auto-delete merged branches +GIT_AUTO_DELETE_MERGED=true +``` + +### Per-Project Configuration + +Create `.git-flow.json` in project root: + +```json +{ + "defaultBase": "development", + "protectedBranches": ["main", "staging", "development"], + "branchPrefixes": ["feat", "fix", "docs", "refactor", "test", "chore"], + "requirePR": { + "main": true, + "staging": true, + "development": false + }, + "squashOnMerge": { + "development": true, + "staging": false, + "main": false + } +} +``` + +## Best Practices + +### Do + +- Keep feature branches short-lived (< 1 week) +- Rebase feature branches on development regularly +- Write descriptive commit messages +- Delete branches after merging +- Tag all releases on main +- Always sync development after hotfixes + +### Avoid + +- Long-lived feature branches +- Direct commits to protected branches +- Force pushing to shared branches +- Merging untested code to staging +- Skipping the development sync after hotfixes + +## Related Documentation + +- [Branching Strategies Skill](/plugins/git-flow/skills/workflow-patterns/branching-strategies.md) +- [git-flow README](/plugins/git-flow/README.md) +- [Conventional Commits](https://www.conventionalcommits.org/) -- 2.49.1