SuperClaude/docs/architecture/pm-agent-auto-activation.md

PM Agent Auto-Activation Architecture

Problem Statement

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やってくれないきがする"

Solution: Behavior-Based Auto-Activation

PM Agent should activate automatically based on context detection, not manual commands.

Architecture Overview

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

Implementation Strategy

1. Session Start Auto-Activation

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.

2. Documentation Guardian (Continuous)

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.

3. Commander Mode (On-Demand)

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.

4. Post-Implementation Auto-Documentation

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.

5. Mistake Handler (Immediate)

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.

Removal of Manual /sc:pm Command

Current State

• /sc:pm command in ~/.claude/commands/sc/pm.md
• Requires user to manually invoke every session
• Inconsistent application

Proposed Change

• Remove /sc:pm command entirely
• Replace with behavior-based auto-activation
• Keep pm-agent persona for all behaviors

Migration Path

Step 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

Benefits

1. No Manual Commands Required

• ✅ PM Agent always active, never forgotten
• ✅ Consistent documentation reading
• ✅ Automatic knowledge base maintenance

2. Context-Aware Activation

• ✅ Right behavior at right time
• ✅ No unnecessary overhead
• ✅ Efficient token usage

3. Guaranteed Documentation Quality

• ✅ Always read relevant docs before changes
• ✅ Automatic pattern documentation
• ✅ Mistake prevention through Reflexion

4. Seamless Orchestration

• ✅ Auto-detects complex tasks
• ✅ Auto-delegates to sub-agents
• ✅ Auto-tracks progress

Token Budget Impact

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

Implementation Checklist

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

Example Workflow (After Implementation)

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]

Conclusion

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.