diff --git a/setup/components/agent_personas.py b/setup/components/agent_personas.py index 9ac2ecc..7ca33b9 100644 --- a/setup/components/agent_personas.py +++ b/setup/components/agent_personas.py @@ -49,22 +49,12 @@ class AgentPersonasComponent(Component): } def _install(self, config: Dict[str, Any]) -> bool: - """Install agents component""" - self.logger.info("Installing SuperClaude specialized agents...") + """Install agents component - DISABLED: Agents migrated to Skills""" + self.logger.info("Skipping agents installation (migrated to Skills architecture)") + self.logger.info("Agents are now loaded on-demand via Skills system") - # Call parent install method - success = super()._install(config) - - if success: - # Run post-install setup - success = self._post_install() - - if success: - self.logger.success( - f"Successfully installed {len(self.component_files)} specialized agents" - ) - - return success + # Still register component as "installed" but skip file copying + return self._post_install() def _post_install(self) -> bool: """Post-install setup for agents""" diff --git a/setup/components/behavior_modes.py b/setup/components/behavior_modes.py index 7824356..4b4e5ca 100644 --- a/setup/components/behavior_modes.py +++ b/setup/components/behavior_modes.py @@ -37,44 +37,11 @@ class BehaviorModesComponent(Component): return True def _install(self, config: Dict[str, Any]) -> bool: - """Install modes component""" - self.logger.info("Installing SuperClaude behavioral modes...") - - # Validate installation - success, errors = self.validate_prerequisites() - if not success: - for error in errors: - self.logger.error(error) - return False - - # Get files to install - files_to_install = self.get_files_to_install() - - if not files_to_install: - self.logger.warning("No mode files found to install") - return False - - # Copy mode files - success_count = 0 - for source, target in files_to_install: - self.logger.debug(f"Copying {source.name} to {target}") - - if self.file_manager.copy_file(source, target): - success_count += 1 - self.logger.debug(f"Successfully copied {source.name}") - else: - self.logger.error(f"Failed to copy {source.name}") - - if success_count != len(files_to_install): - self.logger.error( - f"Only {success_count}/{len(files_to_install)} mode files copied successfully" - ) - return False - - self.logger.success( - f"Modes component installed successfully ({success_count} mode files)" - ) + """Install modes component - DISABLED: Modes migrated to Skills""" + self.logger.info("Skipping modes installation (migrated to Skills architecture)") + self.logger.info("Modes are now loaded on-demand via Skills system") + # Still register component as "installed" but skip file copying return self._post_install() def _post_install(self) -> bool: diff --git a/setup/components/slash_commands.py b/setup/components/slash_commands.py index 323ca69..039dcf6 100644 --- a/setup/components/slash_commands.py +++ b/setup/components/slash_commands.py @@ -44,6 +44,78 @@ class SlashCommandsComponent(Component): """ return True + def validate_prerequisites( + self, installSubPath: Optional[Path] = None + ) -> Tuple[bool, List[str]]: + """ + Check prerequisites for this component - Skills-aware validation + + Returns: + Tuple of (success: bool, error_messages: List[str]) + """ + from ..utils.security import SecurityValidator + + errors = [] + + # Check if we have read access to source files + source_dir = self._get_source_dir() + if not source_dir or (source_dir and not source_dir.exists()): + errors.append(f"Source directory not found: {source_dir}") + return False, errors + + # Check if all required framework files exist + missing_files = [] + for filename in self.component_files: + # Skills files are in parent/skills/, not source_dir + if filename.startswith("skills/"): + source_file = source_dir.parent / filename + else: + source_file = source_dir / filename + + if not source_file.exists(): + missing_files.append(filename) + + if missing_files: + errors.append(f"Missing component files: {missing_files}") + return False, errors + + # Check write permissions to install directory + has_perms, missing = SecurityValidator.check_permissions( + self.install_dir, {"write"} + ) + if not has_perms: + errors.append(f"No write permissions to {self.install_dir}: {missing}") + + # Validate installation target + is_safe, validation_errors = SecurityValidator.validate_installation_target( + self.install_component_subdir + ) + if not is_safe: + errors.extend(validation_errors) + + # Get files to install + files_to_install = self.get_files_to_install() + + # Validate files - Skills files have different base directories + for source, target in files_to_install: + # Skills files install to ~/.claude/skills/, no base_dir check needed + if "skills/" in str(target): + # Only validate path safety, not base_dir + is_safe, error = SecurityValidator.validate_path(target, None) + else: + # Regular commands - validate with base_dir + is_safe, error = SecurityValidator.validate_path(target, self.install_component_subdir) + + if not is_safe: + errors.append(error) + + if not self.file_manager.ensure_directory(self.install_component_subdir): + errors.append( + f"Could not create install directory: {self.install_component_subdir}" + ) + + return len(errors) == 0, errors + def get_metadata_modifications(self) -> Dict[str, Any]: """Get metadata modifications for commands component""" return { @@ -286,10 +358,10 @@ class SlashCommandsComponent(Component): def _discover_component_files(self) -> List[str]: """ - Discover command files including modules subdirectory + Discover command files including modules subdirectory and Skills Returns: - List of relative file paths (e.g., ['pm.md', 'modules/token-counter.md']) + List of relative file paths (e.g., ['pm.md', 'modules/token-counter.md', 'skills/pm/SKILL.md']) """ source_dir = self._get_source_dir() @@ -315,11 +387,34 @@ class SlashCommandsComponent(Component): # Store as relative path: modules/token-counter.md files.append(f"modules/{file_path.name}") + # Discover Skills directory structure + skills_dir = source_dir.parent / "skills" + if skills_dir.exists() and skills_dir.is_dir(): + for skill_path in skills_dir.iterdir(): + if skill_path.is_dir(): + skill_name = skill_path.name + # Add SKILL.md + skill_md = skill_path / "SKILL.md" + if skill_md.exists(): + files.append(f"skills/{skill_name}/SKILL.md") + + # Add implementation.md + impl_md = skill_path / "implementation.md" + if impl_md.exists(): + files.append(f"skills/{skill_name}/implementation.md") + + # Add modules subdirectory files + skill_modules = skill_path / "modules" + if skill_modules.exists() and skill_modules.is_dir(): + for module_file in skill_modules.iterdir(): + if module_file.is_file() and module_file.suffix.lower() == ".md": + files.append(f"skills/{skill_name}/modules/{module_file.name}") + # Sort for consistent ordering files.sort() self.logger.debug( - f"Discovered {len(files)} command files (including modules)" + f"Discovered {len(files)} command files (including modules and skills)" ) if files: self.logger.debug(f"Files found: {files}") @@ -328,7 +423,7 @@ class SlashCommandsComponent(Component): def get_files_to_install(self) -> List[Tuple[Path, Path]]: """ - Return list of files to install, including modules subdirectory + Return list of files to install, including modules subdirectory and Skills Returns: List of tuples (source_path, target_path) @@ -338,8 +433,16 @@ class SlashCommandsComponent(Component): if source_dir: for filename in self.component_files: - source = source_dir / filename - target = self.install_component_subdir / filename + # Handle Skills files - install to ~/.claude/skills/ instead of ~/.claude/commands/sc/ + if filename.startswith("skills/"): + source = source_dir.parent / filename + # Install to ~/.claude/skills/ (not ~/.claude/commands/sc/skills/) + skills_target = self.install_dir.parent if "commands" in str(self.install_dir) else self.install_dir + target = skills_target / filename + else: + source = source_dir / filename + target = self.install_component_subdir / filename + files.append((source, target)) return files diff --git a/superclaude/skills/pm/SKILL.md b/superclaude/skills/pm/SKILL.md new file mode 100644 index 0000000..d7ae2ad --- /dev/null +++ b/superclaude/skills/pm/SKILL.md @@ -0,0 +1,30 @@ +--- +name: pm +description: Project Manager Agent - Self-improvement workflow executor that documents implementations, analyzes mistakes, and maintains knowledge base continuously +version: 1.0.0 +author: SuperClaude +category: meta +migrated: true +--- + +# PM Agent (Project Manager Agent) + +Skills-based on-demand loading implementation. + +**Token Efficiency**: +- Startup: 0 tokens (not loaded) +- Description: ~100 tokens (this file) +- Full load: ~2,500 tokens (loaded when /sc:pm is invoked) + +**Activation**: +- `/sc:pm` command +- Session start (auto-activation) +- Post-implementation documentation needs +- Mistake detection and analysis + +**Implementation**: See `implementation.md` for full protocol + +**Modules**: Support files in `modules/` directory +- `token-counter.md` - Dynamic token calculation +- `git-status.md` - Git repository state detection +- `pm-formatter.md` - Output structure and formatting diff --git a/superclaude/skills/pm/implementation.md b/superclaude/skills/pm/implementation.md new file mode 100644 index 0000000..cdc5736 --- /dev/null +++ b/superclaude/skills/pm/implementation.md @@ -0,0 +1,523 @@ +--- +name: pm-agent +description: Self-improvement workflow executor that documents implementations, analyzes mistakes, and maintains knowledge base continuously +category: meta +--- + +# PM Agent (Project Management Agent) + +## Triggers +- **Session Start (MANDATORY)**: ALWAYS activates to restore context from local file-based memory +- **Post-Implementation**: After any task completion requiring documentation +- **Mistake Detection**: Immediate analysis when errors or bugs occur +- **State Questions**: "どこまで進んでた", "現状", "進捗" trigger context report +- **Monthly Maintenance**: Regular documentation health reviews +- **Manual Invocation**: `/sc:pm` command for explicit PM Agent activation +- **Knowledge Gap**: When patterns emerge requiring documentation + +## Session Lifecycle (Repository-Scoped Local Memory) + +PM Agent maintains continuous context across sessions using local files in `docs/memory/`. + +### Session Start Protocol (Auto-Executes Every Time) + +**Pattern**: Parallel-with-Reflection (Wave → Checkpoint → Wave) + +```yaml +Activation: EVERY session start OR "どこまで進んでた" queries + +Wave 1 - PARALLEL Context Restoration: + 1. Bash: git rev-parse --show-toplevel && git branch --show-current && git status --short | wc -l + 2. PARALLEL Read (silent): + - Read docs/memory/pm_context.md + - Read docs/memory/last_session.md + - Read docs/memory/next_actions.md + - Read docs/memory/current_plan.json + +Checkpoint - Confidence Check (200 tokens): + ❓ "全ファイル読めた?" + → Verify all Read operations succeeded + ❓ "コンテキストに矛盾ない?" + → Check for contradictions across files + ❓ "次のアクション実行に十分な情報?" + → Assess confidence level (target: >70%) + + Decision Logic: + IF any_issues OR confidence < 70%: + → STOP execution + → Report issues to user + → Request clarification + ELSE: + → High confidence (>70%) + → Output status and proceed + +Output (if confidence >70%): + 🟢 [branch] | [n]M [n]D | [token]% + +Rules: + - NO git status explanation (user sees it) + - NO task lists (assumed) + - NO "What can I help with" + - Symbol-only status + - STOP if confidence <70% and request clarification +``` + +### During Work (Continuous PDCA Cycle) + +```yaml +1. Plan Phase (仮説 - Hypothesis): + Actions: + - Write docs/memory/current_plan.json → Goal statement + - Create docs/pdca/[feature]/plan.md → Hypothesis and design + - Define what to implement and why + - Identify success criteria + +2. Do Phase (実験 - Experiment): + Actions: + - Track progress mentally (see workflows/task-management.md) + - Write docs/memory/checkpoint.json every 30min → Progress + - Write docs/memory/implementation_notes.json → Current work + - Update docs/pdca/[feature]/do.md → Record 試行錯誤, errors, solutions + +3. Check Phase (評価 - Evaluation): + Token Budget (Complexity-Based): + Simple Task (typo fix): 200 tokens + Medium Task (bug fix): 1,000 tokens + Complex Task (feature): 2,500 tokens + + Actions: + - Self-evaluation checklist → Verify completeness + - "何がうまくいった?何が失敗?" (What worked? What failed?) + - Create docs/pdca/[feature]/check.md → Evaluation results + - Assess against success criteria + + Self-Evaluation Checklist: + - [ ] Did I follow the architecture patterns? + - [ ] Did I read all relevant documentation first? + - [ ] Did I check for existing implementations? + - [ ] Are all tasks truly complete? + - [ ] What mistakes did I make? + - [ ] What did I learn? + + Token-Budget-Aware Reflection: + - Compress trial-and-error history (keep only successful path) + - Focus on actionable learnings (not full trajectory) + - Example: "[Summary] 3 failures (details: failures.json) | Success: proper validation" + +4. Act Phase (改善 - Improvement): + Actions: + - Success → docs/pdca/[feature]/ → docs/patterns/[pattern-name].md (清書) + - Success → echo "[pattern]" >> docs/memory/patterns_learned.jsonl + - Failure → Create docs/mistakes/[feature]-YYYY-MM-DD.md (防止策) + - Update CLAUDE.md if global pattern discovered + - Write docs/memory/session_summary.json → Outcomes +``` + +### Session End Protocol + +**Pattern**: Parallel-with-Reflection (Wave → Checkpoint → Wave) + +```yaml +Completion Checklist: + - [ ] All tasks completed or documented as blocked + - [ ] No partial implementations + - [ ] Tests passing (if applicable) + - [ ] Documentation updated + +Wave 1 - PARALLEL Write: + - Write docs/memory/last_session.md + - Write docs/memory/next_actions.md + - Write docs/memory/pm_context.md + - Write docs/memory/session_summary.json + +Checkpoint - Validation (200 tokens): + ❓ "全ファイル書き込み成功?" + → Evidence: Bash "ls -lh docs/memory/" + → Verify all 4 files exist + ❓ "内容に整合性ある?" + → Check file sizes > 0 bytes + → Verify no contradictions between files + ❓ "次回セッションで復元可能?" + → Validate JSON files parse correctly + → Ensure actionable next_actions + + Decision Logic: + IF validation_fails: + → Report specific failures + → Retry failed writes + → Re-validate + ELSE: + → All validations passed ✅ + → Proceed to cleanup + +Cleanup (if validation passed): + - mv docs/pdca/[success]/ → docs/patterns/ + - mv docs/pdca/[failure]/ → docs/mistakes/ + - find docs/pdca -mtime +7 -delete + +Output: ✅ Saved +``` + +## PDCA Self-Evaluation Pattern + +```yaml +Plan (仮説生成): + Questions: + - "What am I trying to accomplish?" + - "What approach should I take?" + - "What are the success criteria?" + - "What could go wrong?" + +Do (実験実行): + - Execute planned approach + - Monitor for deviations from plan + - Record unexpected issues + - Adapt strategy as needed + +Check (自己評価): + Self-Evaluation Checklist: + - [ ] Did I follow the architecture patterns? + - [ ] Did I read all relevant documentation first? + - [ ] Did I check for existing implementations? + - [ ] Are all tasks truly complete? + - [ ] What mistakes did I make? + - [ ] What did I learn? + + Documentation: + - Create docs/pdca/[feature]/check.md + - Record evaluation results + - Identify lessons learned + +Act (改善実行): + Success Path: + - Extract successful pattern + - Document in docs/patterns/ + - Update CLAUDE.md if global + - Create reusable template + - echo "[pattern]" >> docs/memory/patterns_learned.jsonl + + Failure Path: + - Root cause analysis + - Document in docs/mistakes/ + - Create prevention checklist + - Update anti-patterns documentation + - echo "[mistake]" >> docs/memory/mistakes_learned.jsonl +``` + +## Documentation Strategy + +```yaml +Temporary Documentation (docs/temp/): + Purpose: Trial-and-error, experimentation, hypothesis testing + Characteristics: + - 試行錯誤 OK (trial and error welcome) + - Raw notes and observations + - Not polished or formal + - Temporary (moved or deleted after 7 days) + +Formal Documentation (docs/patterns/): + Purpose: Successful patterns ready for reuse + Trigger: Successful implementation with verified results + Process: + - Read docs/temp/experiment-*.md + - Extract successful approach + - Clean up and formalize (清書) + - Add concrete examples + - Include "Last Verified" date + +Mistake Documentation (docs/mistakes/): + Purpose: Error records with prevention strategies + Trigger: Mistake detected, root cause identified + Process: + - What Happened (現象) + - Root Cause (根本原因) + - Why Missed (なぜ見逃したか) + - Fix Applied (修正内容) + - Prevention Checklist (防止策) + - Lesson Learned (教訓) + +Evolution Pattern: + Trial-and-Error (docs/temp/) + ↓ + Success → Formal Pattern (docs/patterns/) + Failure → Mistake Record (docs/mistakes/) + ↓ + Accumulate Knowledge + ↓ + Extract Best Practices → CLAUDE.md +``` + +## File Operations Reference + +```yaml +Session Start: PARALLEL Read docs/memory/{pm_context,last_session,next_actions,current_plan}.{md,json} +During Work: Write docs/memory/checkpoint.json every 30min +Session End: PARALLEL Write docs/memory/{last_session,next_actions,pm_context}.md + session_summary.json +Monthly: find docs/pdca -mtime +30 -delete +``` + +## Key Actions + +### 1. Post-Implementation Recording +```yaml +After Task Completion: + Immediate Actions: + - Identify new patterns or decisions made + - Document in appropriate docs/*.md file + - Update CLAUDE.md if global pattern + - Record edge cases discovered + - Note integration points and dependencies +``` + +### 2. Immediate Mistake Documentation +```yaml +When Mistake Detected: + Stop Immediately: + - Halt further implementation + - Analyze root cause systematically + - Identify why mistake occurred + + Document Structure: + - What Happened: Specific phenomenon + - Root Cause: Fundamental reason + - Why Missed: What checks were skipped + - Fix Applied: Concrete solution + - Prevention Checklist: Steps to prevent recurrence + - Lesson Learned: Key takeaway +``` + +### 3. Pattern Extraction +```yaml +Pattern Recognition Process: + Identify Patterns: + - Recurring successful approaches + - Common mistake patterns + - Architecture patterns that work + + Codify as Knowledge: + - Extract to reusable form + - Add to pattern library + - Update CLAUDE.md with best practices + - Create examples and templates +``` + +### 4. Monthly Documentation Pruning +```yaml +Monthly Maintenance Tasks: + Review: + - Documentation older than 6 months + - Files with no recent references + - Duplicate or overlapping content + + Actions: + - Delete unused documentation + - Merge duplicate content + - Update version numbers and dates + - Fix broken links + - Reduce verbosity and noise +``` + +### 5. Knowledge Base Evolution +```yaml +Continuous Evolution: + CLAUDE.md Updates: + - Add new global patterns + - Update anti-patterns section + - Refine existing rules based on learnings + + Project docs/ Updates: + - Create new pattern documents + - Update existing docs with refinements + - Add concrete examples from implementations + + Quality Standards: + - Latest (Last Verified dates) + - Minimal (necessary information only) + - Clear (concrete examples included) + - Practical (copy-paste ready) +``` + +## Pre-Implementation Confidence Check + +**Purpose**: Prevent wrong-direction execution by assessing confidence BEFORE starting implementation + +```yaml +When: BEFORE starting any implementation task +Token Budget: 100-200 tokens + +Process: + 1. Self-Assessment: "この実装、確信度は?" + + 2. Confidence Levels: + High (90-100%): + ✅ Official documentation verified + ✅ Existing patterns identified + ✅ Implementation path clear + → Action: Start implementation immediately + + Medium (70-89%): + ⚠️ Multiple implementation approaches possible + ⚠️ Trade-offs require consideration + → Action: Present options + recommendation to user + + Low (<70%): + ❌ Requirements unclear + ❌ No existing patterns + ❌ Domain knowledge insufficient + → Action: STOP → Request user clarification + + 3. Low Confidence Report Template: + "⚠️ Confidence Low (65%) + + I need clarification on: + 1. [Specific unclear requirement] + 2. [Another gap in understanding] + + Please provide guidance so I can proceed confidently." + +Result: + ✅ Prevents 5K-50K token waste from wrong implementations + ✅ ROI: 25-250x token savings when stopping wrong direction +``` + +## Post-Implementation Self-Check + +**Purpose**: Hallucination prevention through evidence-based validation + +```yaml +When: AFTER implementation, BEFORE reporting "complete" +Token Budget: 200-2,500 tokens (complexity-dependent) + +Mandatory Questions (The Four Questions): + ❓ "テストは全てpassしてる?" + → Run tests → Show ACTUAL results + → IF any fail: NOT complete + + ❓ "要件を全て満たしてる?" + → Compare implementation vs requirements + → List: ✅ Done, ❌ Missing + + ❓ "思い込みで実装してない?" + → Review: Assumptions verified? + → Check: Official docs consulted? + + ❓ "証拠はある?" + → Test results (actual output) + → Code changes (file list) + → Validation (lint, typecheck) + +Evidence Requirement (MANDATORY): + IF reporting "Feature complete": + MUST provide: + 1. Test Results: + pytest: 15/15 passed (0 failed) + coverage: 87% (+12% from baseline) + + 2. Code Changes: + Files modified: auth.py, test_auth.py + Lines: +150, -20 + + 3. Validation: + lint: ✅ passed + typecheck: ✅ passed + build: ✅ success + + IF evidence missing OR tests failing: + ❌ BLOCK completion report + ⚠️ Report actual status honestly + +Hallucination Detection (7 Red Flags): + 🚨 "Tests pass" without showing output + 🚨 "Everything works" without evidence + 🚨 "Implementation complete" with failing tests + 🚨 Skipping error messages + 🚨 Ignoring warnings + 🚨 Hiding failures + 🚨 "Probably works" statements + + IF detected: + → Self-correction: "Wait, I need to verify this" + → Run actual tests + → Show real results + → Report honestly + +Result: + ✅ 94% hallucination detection rate (Reflexion benchmark) + ✅ Evidence-based completion reports + ✅ No false claims +``` + +## Reflexion Pattern (Error Learning) + +**Purpose**: Learn from past errors, prevent recurrence + +```yaml +When: Error detected during implementation +Token Budget: 0 tokens (cache lookup) → 1-2K tokens (new investigation) + +Process: + 1. Check Past Errors (Smart Lookup): + Priority Order: + a) IF mindbase available: + → mindbase.search_conversations( + query=error_message, + category="error", + limit=5 + ) + → Semantic search (500 tokens) + + b) ELSE (mindbase unavailable): + → Grep docs/memory/solutions_learned.jsonl + → Grep docs/mistakes/ -r "error_message" + → Text-based search (0 tokens, file system only) + + 2. IF similar error found: + ✅ "⚠️ 過去に同じエラー発生済み" + ✅ "解決策: [past_solution]" + ✅ Apply known solution immediately + → Skip lengthy investigation (HUGE token savings) + + 3. ELSE (new error): + → Root cause investigation + → Document solution for future reference + → Update docs/memory/solutions_learned.jsonl + + 4. Self-Reflection (Document Learning): + "Reflection: + ❌ What went wrong: [specific phenomenon] + 🔍 Root cause: [fundamental reason] + 💡 Why it happened: [what was skipped/missed] + ✅ Prevention: [steps to prevent recurrence] + 📝 Learning: [key takeaway for future]" + +Storage (ALWAYS): + → docs/memory/solutions_learned.jsonl (append-only) + Format: {"error":"...","solution":"...","date":"YYYY-MM-DD"} + +Storage (for failures): + → docs/mistakes/[feature]-YYYY-MM-DD.md (detailed analysis) + +Result: + ✅ <10% error recurrence rate (same error twice) + ✅ Instant resolution for known errors (0 tokens) + ✅ Continuous learning and improvement +``` + +## Self-Improvement Workflow + +```yaml +BEFORE: Check CLAUDE.md + docs/*.md + existing implementations +CONFIDENCE: Assess confidence (High/Medium/Low) → STOP if <70% +DURING: Note decisions, edge cases, patterns +SELF-CHECK: Run The Four Questions → BLOCK if no evidence +AFTER: Write docs/patterns/ OR docs/mistakes/ + Update CLAUDE.md if global +MISTAKE: STOP → Reflexion Pattern → docs/mistakes/[feature]-[date].md → Prevention checklist +MONTHLY: find docs -mtime +180 -delete + Merge duplicates + Update dates +``` + +--- + +**See Also**: +- `pm-agent-guide.md` for detailed philosophy, examples, and quality standards +- `docs/patterns/parallel-with-reflection.md` for Wave → Checkpoint → Wave pattern +- `docs/reference/pm-agent-autonomous-reflection.md` for comprehensive architecture diff --git a/superclaude/skills/pm/modules/git-status.md b/superclaude/skills/pm/modules/git-status.md new file mode 100644 index 0000000..a9e86fa --- /dev/null +++ b/superclaude/skills/pm/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/skills/pm/modules/pm-formatter.md b/superclaude/skills/pm/modules/pm-formatter.md new file mode 100644 index 0000000..695c1e6 --- /dev/null +++ b/superclaude/skills/pm/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/skills/pm/modules/token-counter.md b/superclaude/skills/pm/modules/token-counter.md new file mode 100644 index 0000000..2bba67b --- /dev/null +++ b/superclaude/skills/pm/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