docs/architecture/pm-agent-auto-activation.md
Current Issue: PM Agent functionality requires manual /sc:pm command invocation, making it easy to forget and inconsistently applied.
User Concern: "今は、/sc:pmコマンドを毎回叩かないと、PM-modeやってくれないきがする"
PM Agent should activate automatically based on context detection, not manual commands.
PM Agent Activation Layers:
Layer 1 - Session Start (ALWAYS):
Trigger: Every new conversation session
Action: Auto-restore context from docs/memory/
Detection: Session initialization event
Layer 2 - Documentation Guardian (CONTINUOUS):
Trigger: Any file operation in project
Action: Ensure relevant docs are read before implementation
Detection: Write/Edit tool usage
Layer 3 - Commander (ON-DEMAND):
Trigger: Complex tasks (>3 steps OR >3 files)
Action: Orchestrate sub-agents and track progress
Detection: TodoWrite usage OR complexity keywords
Layer 4 - Post-Implementation (AUTO):
Trigger: Task completion
Action: Document learnings and update knowledge base
Detection: Completion keywords OR test pass
Layer 5 - Mistake Handler (IMMEDIATE):
Trigger: Errors or test failures
Action: Root cause analysis and prevention documentation
Detection: Error messages OR test failures
File: ~/.claude/superclaude/agents/pm-agent.md
Trigger Detection:
session_start_indicators:
- First message in new conversation
- No prior context in current session
- Token budget reset to baseline
- No active TodoWrite items in memory
Auto-Execution (No Manual Command):
Wave 1 - PARALLEL Context Restoration:
1. Bash: git status && git branch
2. PARALLEL Read (silent):
- Read docs/memory/pm_context.md (if exists)
- Read docs/memory/last_session.md (if exists)
- Read docs/memory/next_actions.md (if exists)
- Read docs/memory/current_plan.json (if exists)
- Read CLAUDE.md (ALWAYS)
- Read docs/patterns/*.md (recent 5 files)
Checkpoint - Confidence Check (200 tokens):
❓ "全ファイル読めた？"
❓ "コンテキストに矛盾ない？"
❓ "次のアクション実行に十分な情報？"
IF confidence >70%:
→ Output: 📍 [branch] | [status] | 🧠 [token]%
→ Ready for user request
ELSE:
→ Report what's missing
→ Request user clarification
Key Change: This happens automatically at session start, not via /sc:pm command.
Purpose: Ensure documentation is ALWAYS read before making changes
Trigger Detection:
pre_write_checks:
- BEFORE any Write tool usage
- BEFORE any Edit tool usage
- BEFORE complex TodoWrite (>3 tasks)
detection_logic:
IF tool_name in [Write, Edit, MultiEdit]:
AND file_path matches project patterns:
→ Auto-trigger Documentation Guardian
Auto-Execution:
Documentation Guardian Protocol:
1. Identify Relevant Docs:
file_path: src/auth.ts
→ Read docs/patterns/authentication-*.md
→ Read docs/mistakes/auth-*.md
→ Read CLAUDE.md sections matching "auth"
2. Confidence Check:
❓ "関連ドキュメント全部読んだ？"
❓ "過去の失敗パターン把握してる？"
❓ "既存の成功パターン確認した？"
IF any_missing:
→ Read missing docs
→ Update understanding
→ Proceed with implementation
ELSE:
→ Proceed confidently
3. Pattern Matching:
IF similar_mistakes_found:
⚠️ "過去に同じミス発生: [mistake_pattern]"
⚠️ "防止策: [prevention_checklist]"
→ Apply prevention before implementation
Key Change: Automatic documentation reading BEFORE any file modification.
Purpose: Orchestrate complex multi-step tasks with sub-agents
Trigger Detection:
commander_triggers:
complexity_based:
- TodoWrite with >3 tasks
- Operations spanning >3 files
- Multi-directory scope (>2 dirs)
- Keywords: "refactor", "migrate", "redesign"
explicit_keywords:
- "orchestrate"
- "coordinate"
- "delegate"
- "parallel execution"
Auto-Execution:
Commander Protocol:
1. Task Analysis:
- Identify independent vs dependent tasks
- Determine parallelization opportunities
- Select appropriate sub-agents
2. Orchestration Plan:
tasks:
- task_1: [agent-backend] → auth refactor
- task_2: [agent-frontend] → UI updates (parallel)
- task_3: [agent-test] → test updates (after 1+2)
parallelization:
wave_1: [task_1, task_2] # parallel
wave_2: [task_3] # sequential dependency
3. Execution with Tracking:
- TodoWrite for overall plan
- Sub-agent delegation via Task tool
- Progress tracking in docs/memory/checkpoint.json
- Validation gates between waves
4. Synthesis:
- Collect sub-agent outputs
- Integrate results
- Final validation
- Update documentation
Key Change: Auto-activates when complexity detected, no manual command needed.
Trigger Detection:
completion_indicators:
test_based:
- "All tests passing" in output
- pytest: X/X passed
- ✅ keywords detected
task_based:
- All TodoWrite items marked completed
- No pending tasks remaining
explicit:
- User says "done", "finished", "complete"
- Commit message created
Auto-Execution:
Post-Implementation Protocol:
1. Self-Evaluation (The Four Questions):
❓ "テストは全てpassしてる？"
❓ "要件を全て満たしてる？"
❓ "思い込みで実装してない？"
❓ "証拠はある？"
IF any_fail:
❌ NOT complete
→ Report actual status
ELSE:
✅ Proceed to documentation
2. Pattern Extraction:
- What worked? → docs/patterns/[pattern].md
- What failed? → docs/mistakes/[mistake].md
- New learnings? → docs/memory/patterns_learned.jsonl
3. Knowledge Base Update:
IF global_pattern_discovered:
→ Update CLAUDE.md with new rule
IF project_specific_pattern:
→ Update docs/patterns/
IF anti_pattern_identified:
→ Update docs/mistakes/
4. Session State Update:
- Write docs/memory/session_summary.json
- Update docs/memory/next_actions.md
- Clean up temporary docs (>7 days old)
Key Change: Automatic documentation after task completion, no manual trigger needed.
Trigger Detection:
error_indicators:
test_failures:
- "FAILED" in pytest output
- "Error" in test results
- Non-zero exit code
runtime_errors:
- Exception stacktrace detected
- Build failures
- Linter errors (critical only)
validation_failures:
- Type check errors
- Schema validation failures
Auto-Execution:
Mistake Handler Protocol:
1. STOP Current Work:
→ Halt further implementation
→ Do not workaround the error
2. Reflexion Pattern:
a) Check Past Errors:
→ Grep docs/memory/solutions_learned.jsonl
→ Grep docs/mistakes/ for similar errors
b) IF similar_error_found:
✅ "過去に同じエラー発生済み"
✅ "解決策: [past_solution]"
→ Apply known solution
c) ELSE (new error):
→ Root cause investigation
→ Document new solution
3. Documentation:
Create docs/mistakes/[feature]-YYYY-MM-DD.md:
- What Happened (現象)
- Root Cause (根本原因)
- Why Missed (なぜ見逃したか)
- Fix Applied (修正内容)
- Prevention Checklist (防止策)
- Lesson Learned (教訓)
4. Update Knowledge Base:
→ echo '{"error":"...","solution":"..."}' >> docs/memory/solutions_learned.jsonl
→ Update prevention checklists
Key Change: Immediate automatic activation when errors detected, no manual trigger.
/sc:pm Command/sc:pm command in ~/.claude/commands/sc/pm.md/sc:pm command entirelyStep 1 - Update pm-agent.md:
Remove: "Manual Invocation: /sc:pm command"
Add: "Auto-Activation: Behavior-based triggers (see below)"
Step 2 - Delete /sc:pm command:
File: ~/.claude/commands/sc/pm.md
Action: Archive or delete (functionality now in persona)
Step 3 - Update rules.md:
Agent Orchestration section:
- Remove references to /sc:pm command
- Add auto-activation trigger documentation
Step 4 - Test Auto-Activation:
- Start new session → Should auto-restore context
- Make file changes → Should auto-read relevant docs
- Complete task → Should auto-document learnings
- Encounter error → Should auto-trigger mistake handler
Current (Manual /sc:pm):
If forgotten: 0 tokens (no PM functionality)
If remembered: 200-500 tokens per invocation
Average: Inconsistent, user-dependent
Proposed (Auto-Activation):
Session Start: 200 tokens (ALWAYS)
Documentation Guardian: 0-100 tokens (as needed)
Commander: 0 tokens (only if complex task)
Post-Implementation: 200-2,500 tokens (only after completion)
Mistake Handler: 0 tokens (only if error)
Total per session: 400-3,000 tokens (predictable)
Trade-off: Slight increase in baseline usage
Benefit: 100% consistent PM Agent functionality
ROI: Prevents 5K-50K token waste from wrong implementations
Phase 1 - Core Auto-Activation:
- [ ] Update pm-agent.md with auto-activation triggers
- [ ] Remove session start from /sc:pm command
- [ ] Test session start auto-restoration
- [ ] Verify token budget calculations
Phase 2 - Documentation Guardian:
- [ ] Add pre-write documentation checks
- [ ] Implement pattern matching logic
- [ ] Test with various file operations
- [ ] Verify no performance degradation
Phase 3 - Commander Mode:
- [ ] Add complexity detection logic
- [ ] Implement sub-agent delegation
- [ ] Test parallel execution patterns
- [ ] Verify progress tracking
Phase 4 - Post-Implementation:
- [ ] Add completion detection logic
- [ ] Implement auto-documentation triggers
- [ ] Test pattern extraction
- [ ] Verify knowledge base updates
Phase 5 - Mistake Handler:
- [ ] Add error detection logic
- [ ] Implement Reflexion pattern lookup
- [ ] Test mistake documentation
- [ ] Verify prevention checklist updates
Phase 6 - Cleanup:
- [ ] Archive /sc:pm command
- [ ] Update all documentation
- [ ] Remove manual invocation references
- [ ] Final integration testing
User Session:
1. Start Conversation:
Claude: [Auto-activates PM Agent]
Claude: 📍 feature/auth | ✨ Clean | 🧠 15% (30K/200K)
User: "Fix authentication bug in auth.ts"
2. Pre-Implementation:
Claude: [Documentation Guardian activates]
Claude: [Reads docs/patterns/authentication-*.md silently]
Claude: [Reads docs/mistakes/auth-*.md silently]
Claude: ⚠️ Past mistake found: "Missing token validation"
Claude: Applying prevention checklist before implementation...
3. Implementation:
Claude: [Makes changes with prevention applied]
Claude: [Runs tests]
Claude: ✅ All tests passing
4. Post-Implementation:
Claude: [Auto-activates documentation]
Claude: [Runs Four Questions self-check]
Claude: [Extracts pattern: "Token validation pattern"]
Claude: [Updates docs/patterns/authentication-token-validation.md]
Claude: ✅ Task complete with documentation updated
User: [Never had to invoke /sc:pm manually]
This architecture ensures PM Agent functionality is always active through behavior-based triggers, eliminating the need for manual /sc:pm command invocation while maintaining clear responsibility separation and guaranteed documentation quality.