feat(plugins): implement Sprint 5 documentation and fixes (#266-#269)

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) Closes #266, Closes #267, Closes #268, Closes #269 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-28 14:24:08 -05:00
8 changed files with 944 additions and 3 deletions
--- 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

 ---

--- 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()
--- 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)"
--- 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(
--- 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`.
--- a/plugins/clarity-assist/docs/ND-SUPPORT.md
+++ 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
--- 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`.
--- a/plugins/git-flow/docs/BRANCHING-STRATEGY.md
+++ 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/)