mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
Revert "feat: comprehensive framework improvements (#447)"
This reverts commit 00706f0ea9.
This commit is contained in:
Mithun Gowda B
@@ -1,220 +0,0 @@
|
||||
# PM Agent Task Management Workflow
|
||||
|
||||
**Purpose**: Lightweight task tracking and progress documentation integrated with PM Agent's learning system.
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
```yaml
|
||||
Storage: docs/memory/tasks/ (visible, searchable, Git-tracked)
|
||||
Format: Markdown (human-readable, grep-friendly)
|
||||
Lifecycle: Plan → Execute → Document → Learn
|
||||
Integration: PM Agent coordinates all phases
|
||||
```
|
||||
|
||||
## Task Management Flow
|
||||
|
||||
### 1. Planning Phase
|
||||
|
||||
**Trigger**: Multi-step tasks (>3 steps), complex scope
|
||||
|
||||
**PM Agent Actions**:
|
||||
```markdown
|
||||
1. Analyze user request
|
||||
2. Break down into steps
|
||||
3. Identify dependencies
|
||||
4. Map parallelization opportunities
|
||||
5. Create task plan in memory
|
||||
```
|
||||
|
||||
**Output**: Mental model only (no file created yet)
|
||||
|
||||
### 2. Execution Phase
|
||||
|
||||
**During Implementation**:
|
||||
```markdown
|
||||
1. Execute steps systematically
|
||||
2. Track progress mentally
|
||||
3. Note blockers and decisions
|
||||
4. Adapt plan as needed
|
||||
```
|
||||
|
||||
**No intermediate files** - keep execution fast and lightweight.
|
||||
|
||||
### 3. Documentation Phase
|
||||
|
||||
**After Completion** (PM Agent auto-activates):
|
||||
```markdown
|
||||
1. Extract implementation patterns
|
||||
2. Document key decisions
|
||||
3. Record learnings
|
||||
4. Save to docs/memory/tasks/[date]-[task-name].md
|
||||
```
|
||||
|
||||
**Template**:
|
||||
```markdown
|
||||
# Task: [Name]
|
||||
Date: YYYY-MM-DD
|
||||
Status: Completed
|
||||
|
||||
## Request
|
||||
[Original user request]
|
||||
|
||||
## Implementation Steps
|
||||
1. Step 1 - [outcome]
|
||||
2. Step 2 - [outcome]
|
||||
3. Step 3 - [outcome]
|
||||
|
||||
## Key Decisions
|
||||
- Decision 1: [rationale]
|
||||
- Decision 2: [rationale]
|
||||
|
||||
## Patterns Discovered
|
||||
- Pattern 1: [description]
|
||||
- Pattern 2: [description]
|
||||
|
||||
## Learnings
|
||||
- Learning 1
|
||||
- Learning 2
|
||||
|
||||
## Files Modified
|
||||
- file1.ts: [changes]
|
||||
- file2.py: [changes]
|
||||
```
|
||||
|
||||
### 4. Learning Phase
|
||||
|
||||
**PM Agent Knowledge Extraction**:
|
||||
```markdown
|
||||
1. Identify reusable patterns
|
||||
2. Extract to docs/patterns/ if applicable
|
||||
3. Update PM Agent knowledge base
|
||||
4. Prune outdated patterns
|
||||
```
|
||||
|
||||
## When to Use Task Management
|
||||
|
||||
**Use When**:
|
||||
- Complex multi-step operations (>3 steps)
|
||||
- Cross-file refactoring
|
||||
- Learning-worthy implementations
|
||||
- Need to track decisions
|
||||
|
||||
**Skip When**:
|
||||
- Simple single-file edits
|
||||
- Trivial bug fixes
|
||||
- Routine operations
|
||||
- Quick experiments
|
||||
|
||||
## Storage Structure
|
||||
|
||||
```
|
||||
docs/
|
||||
└── memory/
|
||||
└── tasks/
|
||||
├── 2025-10-17-auth-implementation.md
|
||||
├── 2025-10-17-api-redesign.md
|
||||
└── README.md (index of all tasks)
|
||||
```
|
||||
|
||||
## Integration with PM Agent
|
||||
|
||||
```yaml
|
||||
PM Agent Activation Points:
|
||||
1. Task Planning: Analyze and break down
|
||||
2. Mid-Task: Note blockers and pivots
|
||||
3. Post-Task: Extract patterns and document
|
||||
4. Monthly: Review and prune task history
|
||||
|
||||
PM Agent Responsibilities:
|
||||
- Task complexity assessment
|
||||
- Step breakdown and dependency mapping
|
||||
- Pattern extraction and knowledge capture
|
||||
- Documentation quality and pruning
|
||||
```
|
||||
|
||||
## Comparison: Old vs New
|
||||
|
||||
```yaml
|
||||
Old Design (Serena + TodoWrite):
|
||||
Storage: ~/.claude/todos/*.json (invisible)
|
||||
Format: JSON (machine-only)
|
||||
Lifecycle: Created → Abandoned → Garbage
|
||||
Result: Empty files, wasted tokens
|
||||
|
||||
New Design (PM Agent + Markdown):
|
||||
Storage: docs/memory/tasks/*.md (visible)
|
||||
Format: Markdown (human-readable)
|
||||
Lifecycle: Plan → Execute → Document → Learn
|
||||
Result: Knowledge accumulation, no garbage
|
||||
```
|
||||
|
||||
## Example Workflow
|
||||
|
||||
**User**: "Implement JWT authentication"
|
||||
|
||||
**PM Agent Planning**:
|
||||
```markdown
|
||||
Mental breakdown:
|
||||
1. Install dependencies (parallel: jwt lib + types)
|
||||
2. Create middleware (sequential: after deps)
|
||||
3. Add route protection (parallel: multiple routes)
|
||||
4. Write tests (sequential: after implementation)
|
||||
|
||||
Estimated: 4 main steps, 2 parallelizable
|
||||
```
|
||||
|
||||
**Execution**: PM Agent coordinates, no files created
|
||||
|
||||
**Documentation** (after completion):
|
||||
```markdown
|
||||
File: docs/memory/tasks/2025-10-17-jwt-auth.md
|
||||
|
||||
# Task: JWT Authentication Implementation
|
||||
Date: 2025-10-17
|
||||
Status: Completed
|
||||
|
||||
## Request
|
||||
Implement JWT authentication for API routes
|
||||
|
||||
## Implementation Steps
|
||||
1. Dependencies - Installed jsonwebtoken + @types/jsonwebtoken
|
||||
2. Middleware - Created auth.middleware.ts with token validation
|
||||
3. Route Protection - Applied to /api/user/* routes
|
||||
4. Tests - Added 8 test cases (auth.test.ts)
|
||||
|
||||
## Key Decisions
|
||||
- Used RS256 (not HS256) for better security
|
||||
- 15min access token, 7day refresh token
|
||||
- Stored keys in environment variables
|
||||
|
||||
## Patterns Discovered
|
||||
- Middleware composition pattern for auth chains
|
||||
- Error handling with custom AuthError class
|
||||
|
||||
## Files Modified
|
||||
- src/middleware/auth.ts: New auth middleware
|
||||
- src/routes/user.ts: Applied middleware
|
||||
- tests/auth.test.ts: New test suite
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
```yaml
|
||||
Visibility: All tasks visible in docs/memory/
|
||||
Searchability: grep-friendly markdown
|
||||
Git History: Task evolution tracked
|
||||
Learning: Patterns extracted automatically
|
||||
No Garbage: Only completed, valuable tasks saved
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
❌ **Don't**: Create task file before completion
|
||||
❌ **Don't**: Document trivial operations
|
||||
❌ **Don't**: Create TODO comments in code
|
||||
❌ **Don't**: Use for session management (separate concern)
|
||||
|
||||
✅ **Do**: Let PM Agent decide when to document
|
||||
✅ **Do**: Focus on learning and patterns
|
||||
✅ **Do**: Keep task files concise
|
||||
✅ **Do**: Review and prune old tasks monthly
|
||||
@@ -149,7 +149,7 @@ def _run_installation(
|
||||
verbose=verbose,
|
||||
quiet=False,
|
||||
yes=True, # Always non-interactive
|
||||
components=["knowledge_base", "modes", "commands", "agents"], # Full install (mcp integrated into airis-mcp-gateway)
|
||||
components=["framework_docs", "modes", "commands", "agents"], # Full install (mcp integrated into airis-mcp-gateway)
|
||||
no_backup=False,
|
||||
list_components=False,
|
||||
diagnose=False,
|
||||
|
||||
@@ -1,231 +0,0 @@
|
||||
---
|
||||
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)
|
||||
@@ -1,251 +0,0 @@
|
||||
---
|
||||
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
|
||||
@@ -1,165 +0,0 @@
|
||||
---
|
||||
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:
|
||||
```
|
||||
<system_warning>Token usage: [used]/[total]; [remaining] remaining</system_warning>
|
||||
```
|
||||
|
||||
**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: <system_warning>Token usage: ...</system_warning>
|
||||
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
|
||||
@@ -1,31 +0,0 @@
|
||||
# Files Moved
|
||||
|
||||
The files in `superclaude/core/` have been reorganized into domain-specific directories:
|
||||
|
||||
## New Structure
|
||||
|
||||
### Framework (思想・行動規範・グローバルフラグ)
|
||||
- `PRINCIPLES.md` → `superclaude/framework/principles.md`
|
||||
- `RULES.md` → `superclaude/framework/rules.md`
|
||||
- `FLAGS.md` → `superclaude/framework/flags.md`
|
||||
|
||||
### Business (ビジネス領域の共通リソース)
|
||||
- `BUSINESS_SYMBOLS.md` → `superclaude/business/symbols.md`
|
||||
- `BUSINESS_PANEL_EXAMPLES.md` → `superclaude/business/examples.md`
|
||||
|
||||
### Research (調査・評価・設定)
|
||||
- `RESEARCH_CONFIG.md` → `superclaude/research/config.md`
|
||||
|
||||
## Rationale
|
||||
|
||||
The `core/` directory was too abstract and made it difficult to find specific documentation. The new structure provides:
|
||||
|
||||
- **Clear domain boundaries**: Easier to navigate and maintain
|
||||
- **Scalability**: Easy to add new directories (e.g., `benchmarks/`, `policies/`)
|
||||
- **Lowercase naming**: Consistent with modern documentation practices
|
||||
|
||||
## Migration
|
||||
|
||||
All internal references have been updated. External references should update to the new paths.
|
||||
|
||||
This directory will be removed in the next major release.
|
||||
Reference in New Issue
Block a user