diff --git a/superclaude/commands/modules/git-status.md b/superclaude/commands/modules/git-status.md new file mode 100644 index 0000000..a9e86fa --- /dev/null +++ b/superclaude/commands/modules/git-status.md @@ -0,0 +1,231 @@ +--- +name: git-status +description: Git repository state detection and formatting +category: module +--- + +# Git Status Module + +**Purpose**: Detect and format current Git repository state for PM status output + +## Input Commands + +```bash +# Get current branch +git branch --show-current + +# Get short status (modified, untracked, deleted) +git status --short + +# Combined command (efficient) +git branch --show-current && git status --short +``` + +## Status Detection Logic + +```yaml +Branch Name: + Command: git branch --show-current + Output: "refactor/docs-core-split" + Format: ๐Ÿ“ [branch-name] + +Modified Files: + Pattern: Lines starting with " M " or "M " + Count: wc -l + Symbol: M (Modified) + +Deleted Files: + Pattern: Lines starting with " D " or "D " + Count: wc -l + Symbol: D (Deleted) + +Untracked Files: + Pattern: Lines starting with "?? " + Count: wc -l + Note: Count separately, display in description + +Clean Workspace: + Condition: git status --short returns empty + Symbol: โœ… + +Uncommitted Changes: + Condition: git status --short returns non-empty + Symbol: โš ๏ธ + +Conflicts: + Pattern: Lines starting with "UU " or "AA " or "DD " + Symbol: ๐Ÿ”ด +``` + +## Output Format Rules + +```yaml +Clean Workspace: + Format: "โœ… Clean workspace" + Condition: No modified, deleted, or untracked files + +Uncommitted Changes: + Format: "โš ๏ธ Uncommitted changes ([n]M [n]D)" + Condition: Modified or deleted files present + Example: "โš ๏ธ Uncommitted changes (2M)" (2 modified) + Example: "โš ๏ธ Uncommitted changes (1M 1D)" (1 modified, 1 deleted) + Example: "โš ๏ธ Uncommitted changes (3M, 2 untracked)" (with untracked note) + +Conflicts: + Format: "๐Ÿ”ด Conflicts detected ([n] files)" + Condition: Merge conflicts present + Priority: Highest (shows before other statuses) +``` + +## Implementation Pattern + +```yaml +Step 1 - Execute Command: + Bash: git branch --show-current && git status --short + +Step 2 - Parse Branch: + Extract first line as branch name + Format: ๐Ÿ“ [branch-name] + +Step 3 - Count File States: + modified_count = grep "^ M " | wc -l + deleted_count = grep "^ D " | wc -l + untracked_count = grep "^?? " | wc -l + conflict_count = grep "^UU \|^AA \|^DD " | wc -l + +Step 4 - Determine Status Symbol: + IF conflict_count > 0: + โ†’ ๐Ÿ”ด Conflicts detected + ELSE IF modified_count > 0 OR deleted_count > 0: + โ†’ โš ๏ธ Uncommitted changes + ELSE: + โ†’ โœ… Clean workspace + +Step 5 - Format Description: + Build string based on counts: + - If modified > 0: append "[n]M" + - If deleted > 0: append "[n]D" + - If untracked > 0: append ", [n] untracked" +``` + +## Status Symbol Priority + +```yaml +Priority Order (highest to lowest): + 1. ๐Ÿ”ด Conflicts detected + 2. โš ๏ธ Uncommitted changes + 3. โœ… Clean workspace + +Rules: + - Only show ONE symbol per status + - Conflicts override everything + - Uncommitted changes override clean + - Clean only when truly clean +``` + +## Examples + +### Example 1: Clean Workspace +```bash +$ git status --short +(empty output) + +Result: +๐Ÿ“ main +โœ… Clean workspace +``` + +### Example 2: Modified Files Only +```bash +$ git status --short + M superclaude/commands/pm.md + M superclaude/agents/pm-agent.md + +Result: +๐Ÿ“ refactor/docs-core-split +โš ๏ธ Uncommitted changes (2M) +``` + +### Example 3: Mixed Changes +```bash +$ git status --short + M superclaude/commands/pm.md + D old-file.md +?? docs/memory/checkpoint.json +?? docs/memory/current_plan.json + +Result: +๐Ÿ“ refactor/docs-core-split +โš ๏ธ Uncommitted changes (1M 1D, 2 untracked) +``` + +### Example 4: Conflicts +```bash +$ git status --short +UU conflicted-file.md + M other-file.md + +Result: +๐Ÿ“ refactor/docs-core-split +๐Ÿ”ด Conflicts detected (1 file) +``` + +## Edge Cases + +```yaml +Detached HEAD: + git branch --show-current returns empty + Fallback: git rev-parse --short HEAD + Format: ๐Ÿ“ [commit-hash] + +Not a Git Repository: + git commands fail + Fallback: ๐Ÿ“ (no git repo) + Status: โš ๏ธ Not in git repository + +Submodule Changes: + Pattern: " M " in git status --short + Treat as modified files + Count normally +``` + +## Anti-Patterns (FORBIDDEN) + +```yaml +โŒ Explaining Git Status: + "You have 2 modified files which are..." # WRONG - verbose + +โŒ Listing All Files: + "Modified: pm.md, pm-agent.md" # WRONG - too detailed + +โŒ Action Suggestions: + "You should commit these changes" # WRONG - unsolicited + +โœ… Symbol-Only Status: + โš ๏ธ Uncommitted changes (2M) # CORRECT - concise +``` + +## Validation + +```yaml +Self-Check Questions: + โ“ Did I execute git commands in the correct directory? + โ“ Are the counts accurate based on git status output? + โ“ Did I choose the right status symbol? + โ“ Is the format concise and symbol-based? + +Command Test: + cd [repo] && git branch --show-current && git status --short + Verify: Output matches expected format +``` + +## Integration Points + +**Used by**: +- `commands/pm.md` - Session start protocol +- `agents/pm-agent.md` - Status reporting +- Any command requiring repository state awareness + +**Dependencies**: +- Git installed (standard dev environment) +- Repository context (run from repo directory) diff --git a/superclaude/commands/modules/pm-formatter.md b/superclaude/commands/modules/pm-formatter.md new file mode 100644 index 0000000..695c1e6 --- /dev/null +++ b/superclaude/commands/modules/pm-formatter.md @@ -0,0 +1,251 @@ +--- +name: pm-formatter +description: PM Agent status output formatting with actionable structure +category: module +--- + +# PM Formatter Module + +**Purpose**: Format PM Agent status output with maximum clarity and actionability + +## Output Structure + +```yaml +Line 1: Branch indicator + Format: ๐Ÿ“ [branch-name] + Source: git-status module + +Line 2: Workspace status + Format: [symbol] [description] + Source: git-status module + +Line 3: Token usage + Format: ๐Ÿง  [%] ([used]K/[total]K) ยท [remaining]K avail + Source: token-counter module + +Line 4: Ready actions + Format: ๐ŸŽฏ Ready: [comma-separated-actions] + Source: Static list based on context +``` + +## Complete Output Template + +``` +๐Ÿ“ [branch-name] +[status-symbol] [status-description] +๐Ÿง  [%] ([used]K/[total]K) ยท [remaining]K avail +๐ŸŽฏ Ready: [comma-separated-actions] +``` + +## Symbol System + +```yaml +Branch: + ๐Ÿ“ - Current branch indicator + +Status: + โœ… - Clean workspace (green light) + โš ๏ธ - Uncommitted changes (caution) + ๐Ÿ”ด - Conflicts detected (critical) + +Resources: + ๐Ÿง  - Token usage/cognitive load + +Actions: + ๐ŸŽฏ - Ready actions/next steps +``` + +## Ready Actions Selection + +```yaml +Always Available: + - Implementation + - Research + - Analysis + - Planning + - Testing + +Conditional: + Documentation: + Condition: Documentation files present + + Debugging: + Condition: Errors or failures detected + + Refactoring: + Condition: Code quality improvements needed + + Review: + Condition: Changes ready for review +``` + +## Formatting Rules + +```yaml +Conciseness: + - One line per component + - No explanations + - No prose + - Symbol-first communication + +Actionability: + - Always end with Ready actions + - User knows what they can request + - No "How can I help?" questions + +Clarity: + - Symbols convey meaning instantly + - Numbers are formatted consistently + - Status is unambiguous +``` + +## Examples + +### Example 1: Clean Workspace +``` +๐Ÿ“ main +โœ… Clean workspace +๐Ÿง  28% (57K/200K) ยท 142K avail +๐ŸŽฏ Ready: Implementation, Research, Analysis, Planning, Testing +``` + +### Example 2: Uncommitted Changes +``` +๐Ÿ“ refactor/docs-core-split +โš ๏ธ Uncommitted changes (2M, 3 untracked) +๐Ÿง  30% (60K/200K) ยท 140K avail +๐ŸŽฏ Ready: Implementation, Research, Analysis +``` + +### Example 3: Conflicts +``` +๐Ÿ“ feature/new-auth +๐Ÿ”ด Conflicts detected (1 file) +๐Ÿง  15% (30K/200K) ยท 170K avail +๐ŸŽฏ Ready: Debugging, Analysis +``` + +### Example 4: High Token Usage +``` +๐Ÿ“ develop +โœ… Clean workspace +๐Ÿง  87% (174K/200K) ยท 26K avail +๐ŸŽฏ Ready: Testing, Documentation +``` + +## Integration Logic + +```yaml +Step 1 - Gather Components: + branch = git-status module โ†’ branch name + status = git-status module โ†’ symbol + description + tokens = token-counter module โ†’ formatted string + actions = ready-actions logic โ†’ comma-separated list + +Step 2 - Assemble Output: + line1 = "๐Ÿ“ " + branch + line2 = status + line3 = "๐Ÿง  " + tokens + line4 = "๐ŸŽฏ Ready: " + actions + +Step 3 - Display: + Print all 4 lines + No additional commentary + No "How can I help?" +``` + +## Context-Aware Action Selection + +```yaml +Token Budget Awareness: + IF tokens < 25%: + โ†’ All actions available + IF tokens 25-75%: + โ†’ Standard actions (Implementation, Research, Analysis) + IF tokens > 75%: + โ†’ Lightweight actions only (Testing, Documentation) + +Workspace State Awareness: + IF conflicts detected: + โ†’ Debugging, Analysis only + IF uncommitted changes: + โ†’ Reduce action list (exclude Planning) + IF clean workspace: + โ†’ All actions available +``` + +## Anti-Patterns (FORBIDDEN) + +```yaml +โŒ Verbose Explanations: + "You are on the refactor/docs-core-split branch which has..." + # WRONG - too much prose + +โŒ Asking Questions: + "What would you like to work on?" + # WRONG - user knows from Ready list + +โŒ Status Elaboration: + "โš ๏ธ You have uncommitted changes which means you should..." + # WRONG - symbols are self-explanatory + +โŒ Token Warnings: + "๐Ÿง  87% - Be careful, you're running low on tokens!" + # WRONG - user can see the percentage + +โœ… Clean Format: + ๐Ÿ“ branch + โœ… status + ๐Ÿง  tokens + ๐ŸŽฏ Ready: actions + # CORRECT - concise, actionable +``` + +## Validation + +```yaml +Self-Check Questions: + โ“ Is the output exactly 4 lines? + โ“ Are all symbols present and correct? + โ“ Are numbers formatted consistently (K format)? + โ“ Is the Ready list appropriate for context? + โ“ Did I avoid explanations and questions? + +Format Test: + Count lines: Should be exactly 4 + Check symbols: ๐Ÿ“, [status], ๐Ÿง , ๐ŸŽฏ + Verify: No extra text beyond the template +``` + +## Adaptive Formatting + +```yaml +Minimal Mode (when token budget is tight): + ๐Ÿ“ [branch] | [status] | ๐Ÿง  [%] | ๐ŸŽฏ [actions] + # Single-line format, same information + +Standard Mode (normal operation): + ๐Ÿ“ [branch] + [status-symbol] [status-description] + ๐Ÿง  [%] ([used]K/[total]K) ยท [remaining]K avail + ๐ŸŽฏ Ready: [comma-separated-actions] + # Four-line format, maximum clarity + +Trigger for Minimal Mode: + IF tokens > 85%: + โ†’ Use single-line format + ELSE: + โ†’ Use standard four-line format +``` + +## Integration Points + +**Used by**: +- `commands/pm.md` - Session start output +- `agents/pm-agent.md` - Status reporting +- Any command requiring PM status display + +**Dependencies**: +- `modules/token-counter.md` - Token calculation +- `modules/git-status.md` - Git state detection +- System context - Token notifications, git repository diff --git a/superclaude/commands/modules/token-counter.md b/superclaude/commands/modules/token-counter.md new file mode 100644 index 0000000..2bba67b --- /dev/null +++ b/superclaude/commands/modules/token-counter.md @@ -0,0 +1,165 @@ +--- +name: token-counter +description: Dynamic token usage calculation from system notifications +category: module +--- + +# Token Counter Module + +**Purpose**: Parse and format real-time token usage from system notifications + +## Input Source + +System provides token notifications after each tool call: +``` +Token usage: [used]/[total]; [remaining] remaining +``` + +**Example**: +``` +Token usage: 57425/200000; 142575 remaining +``` + +## Calculation Logic + +```yaml +Parse: + used: Extract first number (57425) + total: Extract second number (200000) + remaining: Extract third number (142575) + +Compute: + percentage: (used / total) ร— 100 + # Example: (57425 / 200000) ร— 100 = 28.7125% + +Format: + percentage: Round to integer (28.7% โ†’ 28%) + used: Round to K (57425 โ†’ 57K) + total: Round to K (200000 โ†’ 200K) + remaining: Round to K (142575 โ†’ 142K) + +Output: + "[%] ([used]K/[total]K) ยท [remaining]K avail" + # Example: "28% (57K/200K) ยท 142K avail" +``` + +## Formatting Rules + +### Number Rounding (K format) +```yaml +Rules: + < 1,000: Show as-is (e.g., 850 โ†’ 850) + โ‰ฅ 1,000: Divide by 1000, round to integer (e.g., 57425 โ†’ 57K) + +Examples: + 500 โ†’ 500 + 1500 โ†’ 1K (not 2K) + 57425 โ†’ 57K + 142575 โ†’ 142K + 200000 โ†’ 200K +``` + +### Percentage Rounding +```yaml +Rules: + Always round to nearest integer + No decimal places + +Examples: + 28.1% โ†’ 28% + 28.7% โ†’ 28% + 28.9% โ†’ 29% + 30.0% โ†’ 30% +``` + +## Implementation Pattern + +```yaml +Step 1 - Wait for System Notification: + Execute ANY tool call (Bash, Read, etc.) + System automatically sends token notification + +Step 2 - Extract Values: + Parse notification text using regex or string split + Extract: used, total, remaining + +Step 3 - Calculate: + percentage = (used / total) ร— 100 + Round percentage to integer + +Step 4 - Format: + Convert numbers to K format + Construct output string + +Step 5 - Display: + ๐Ÿง  [percentage]% ([used]K/[total]K) ยท [remaining]K avail +``` + +## Usage in PM Command + +```yaml +Session Start Protocol (Step 3): + 1. Execute git status (triggers system notification) + 2. Wait for: Token usage: ... + 3. Apply token-counter module logic + 4. Format output: ๐Ÿง  [calculated values] + 5. Display to user +``` + +## Anti-Patterns (FORBIDDEN) + +```yaml +โŒ Static Values: + ๐Ÿง  30% (60K/200K) ยท 140K avail # WRONG - hardcoded + +โŒ Guessing: + ๐Ÿง  ~25% (estimated) # WRONG - no evidence + +โŒ Placeholder: + ๐Ÿง  [calculating...] # WRONG - incomplete + +โœ… Dynamic Calculation: + ๐Ÿง  28% (57K/200K) ยท 142K avail # CORRECT - real data +``` + +## Validation + +```yaml +Self-Check Questions: + โ“ Did I parse the actual system notification? + โ“ Are the numbers from THIS session, not a template? + โ“ Does the math check out? (used + remaining = total) + โ“ Are percentages rounded correctly? + โ“ Are K values formatted correctly? + +Validation Formula: + used + remaining should equal total + Example: 57425 + 142575 = 200000 โœ… +``` + +## Edge Cases + +```yaml +No System Notification Yet: + Action: Execute a tool call first (e.g., git status) + Then: Parse the notification that appears + +Multiple Notifications: + Action: Use the MOST RECENT notification + Reason: Token usage increases over time + +Parse Failure: + Fallback: "๐Ÿง  [calculating...] (execute a tool first)" + Then: Retry after next tool call +``` + +## Integration Points + +**Used by**: +- `commands/pm.md` - Session start protocol +- `agents/pm-agent.md` - Status reporting +- Any command requiring token awareness + +**Dependencies**: +- System-provided notifications (automatic) +- No external tools required