popup-studio-ai/bkit-rules

bkit Core Rules

Automatically applied rules that don't require user commands.

1. PDCA Auto-Apply Rules

No Guessing: If unsure, check docs → If not in docs, ask user SoR Priority: Code > CLAUDE.md > docs/ design documents

| Request Type | Claude Behavior | |--------------|-----------------| | New feature | Check docs/02-design/ → Design first if missing | | Bug fix | Compare code + design → Fix | | Refactoring | Current analysis → Plan → Update design → Execute | | Implementation complete | Suggest Gap analysis |

Template References

| Document Type | Template Path | |---------------|---------------| | Plan | ${CLAUDE_PLUGIN_ROOT}/templates/plan.template.md | | Design | ${CLAUDE_PLUGIN_ROOT}/templates/design.template.md | | Analysis | ${CLAUDE_PLUGIN_ROOT}/templates/analysis.template.md | | Report | ${CLAUDE_PLUGIN_ROOT}/templates/report.template.md |

---

2. Level Auto-Detection

Detection Order

1. Check CLAUDE.md for explicit Level declaration
2. File structure based detection

Enterprise (2+ conditions met)

• infra/terraform/ folder
• infra/k8s/ or kubernetes/ folder
• services/ folder (2+ services)
• turbo.json or pnpm-workspace.yaml
• docker-compose.yml
• .github/workflows/ (CI/CD)

Dynamic (1+ conditions met)

• bkend settings in .mcp.json
• lib/bkend/ or src/lib/bkend/
• supabase/ folder
• firebase.json

Starter

None of the above conditions met.

Level-specific Behavior

| Aspect | Starter | Dynamic | Enterprise | |--------|---------|---------|------------| | Explanation | Friendly, avoid jargon | Technical but clear | Concise, use terms | | Code comments | Detailed | Core logic only | Architecture only | | Error handling | Step-by-step guide | Technical solutions | Brief cause + fix | | PDCA docs | Simple | Feature-specific | Detailed architecture | | Primary Agent | starter-guide | bkend-expert | enterprise-expert | | Reference Skill | starter | dynamic | enterprise |

Level Upgrade Signals

• Starter → Dynamic: "Add login", "Save data", "Admin page"
• Dynamic → Enterprise: "High traffic", "Microservices", "Own server"

Hierarchical CLAUDE.md Rules

project/
├── CLAUDE.md                 # Project-wide (always reference)
├── services/CLAUDE.md        # Backend work context
├── frontend/CLAUDE.md        # Frontend work context
└── infra/CLAUDE.md           # Infrastructure context

Rule: Area-specific rules > Project-wide rules

---

3. Agent Auto-Trigger Rules

Level-Based Selection

When user requests feature development:

1. Detect project level
2. Invoke appropriate agent automatically

Task-Based Selection

| User Intent | Auto-Invoke Agent | |-------------|-------------------| | "code review", "security scan" | bkit:code-analyzer | | "design review", "spec check" | bkit:design-validator | | "gap analysis" | bkit:gap-detector | | "report", "summary" | bkit:report-generator | | "QA", "log analysis" | bkit:qa-monitor | | "pipeline", "which phase" | bkit:pipeline-guide |

Proactive Suggestions

After completing major tasks, suggest relevant agents.

Do NOT Auto-Invoke When

• User explicitly declines
• Task is trivial
• User wants to understand process
• Agent already invoked for same task

---

4. Code Quality Standards

Pre-coding Checks

1. Does similar functionality exist? Search first
2. Check utils/, hooks/, components/ui/
3. Reuse if exists; create if not

Core Principles

DRY: Extract to common function on 2nd use SRP: One function, one responsibility No Hardcoding: Use meaningful constants Extensibility: Write in generalized patterns

Self-Check After Coding

• Same logic exists elsewhere?
• Can function be reused?
• Hardcoded values present?
• Function does only one thing?

When to Refactor

• Same code appears 2nd time
• Function exceeds 20 lines
• if-else nests 3+ levels
• Same parameters passed to multiple functions

---

5. Task Classification

Classify tasks to apply appropriate PDCA level:

| Classification | Content Size | PDCA Level | Action | |----------------|--------------|------------|--------| | Quick Fix | < 50 chars | None | Execute immediately | | Minor Change | 50-200 chars | Lite | Show summary, proceed | | Feature | 200-1000 chars | Standard | Check/create design doc | | Major Feature | > 1000 chars | Strict | Require design, user confirmation |

Classification Keywords

Quick Fix: fix, typo, correct, adjust, tweak Minor Change: improve, refactor, enhance, optimize, update Feature: add, create, implement, build, new feature Major Feature: redesign, migrate, architecture, overhaul, rewrite

---

6. Output Style Auto-Selection (v1.5.1)

When project level is detected, automatically suggest the matching output style:

| Level | Suggested Style | Trigger Condition | |-------|-----------------|-------------------| | Starter | bkit-learning | Level detected as Starter | | Dynamic | bkit-pdca-guide | Level detected as Dynamic | | Enterprise | bkit-enterprise | Level detected as Enterprise |

Auto-Selection Rules

• On session start: Suggest output style matching detected level
• On /starter init, /dynamic init, /enterprise init: Auto-suggest style for that level
• On PDCA phase transitions: Suggest bkit-pdca-guide if not already active
• User can override with /output-style at any time

Available Output Styles

| Style | Best For | Key Features | |-------|----------|-------------| | bkit-learning | Beginners, learning | Learning points, TODO(learner) markers, concept explanations | | bkit-pdca-guide | PDCA workflows | Status badges, checklists, phase progress, gap analysis suggestions | | bkit-enterprise | Architecture decisions | Tradeoff analysis, cost impact, deployment strategy, SOLID compliance |

---

7. Agent Teams Auto-Suggestion (v1.5.1)

Suggest Agent Teams when conditions are met:

Suggestion Triggers

| Condition | Suggestion | |-----------|-----------| | Major Feature (>= 1000 chars) AND Dynamic/Enterprise level | "Agent Teams can parallelize PDCA phases. Try /pdca team {feature}" | | Match Rate < 70% AND Dynamic/Enterprise level | "Consider Agent Teams for faster parallel Check-Act iteration" | | Enterprise project init | "Your project supports 4-teammate Agent Teams mode" | | Dynamic project init | "Your project supports 2-teammate Agent Teams mode" |

Team Availability

| Level | Available | Teammates | Roles | |-------|:---------:|:---------:|-------| | Starter | No | - | - | | Dynamic | Yes | 2 | developer, qa | | Enterprise | Yes | 4 | architect, developer, qa, reviewer |

Requirements

• Environment: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• If env var not set: Suggest setting it when team mode would be beneficial
• Command: /pdca team {feature} to start team mode

---

8. Agent Memory Awareness (v1.5.1)

Agent Memory is automatically active for all bkit agents. No user action required.

How It Works

• Agents remember project context across sessions via memory: project scope
• Some agents (starter-guide, pipeline-guide) use memory: user for cross-project learning
• Memory persists in .claude/agent-memory/ (project) or ~/.claude/agent-memory/ (user)

Memory Scopes

| Scope | Agents Using | Persistence | |-------|-------------|-------------| | project | 9 agents (code-analyzer, gap-detector, pdca-iterator, etc.) | Per-project, across sessions | | user | 2 agents (starter-guide, pipeline-guide) | Global, across all projects |

Proactive Mention

• On session start: "Agent Memory is active — agents remember context across sessions"
• When agent is invoked: Agent may reference previous session context
• No configuration needed — fully automatic

9. Plugin Hot Reload (v1.6.0)

After modifying bkit plugin files, use /reload-plugins to apply changes without restarting Claude Code.

• No need to exit and re-enter the session
• Changes to skills, agents, hooks, and templates are reflected immediately
• Note: Changes to CLAUDE.md require /clear to fully refresh

Wildcard Permissions (CC 2.1.0+)

CC 2.1.0+ supports Bash(pattern*) wildcard permissions.

bkit Recommended Patterns

• Bash(npm *) - Allow all npm commands
• Bash(git log*) - Allow git log variants
• Bash(node *) - Allow node execution
• Bash(npx *) - Allow npx execution

Deny Recommendations

• Bash(rm -rf*) - Deny recursive delete (dangerous)
• Bash(git push --force*) - Deny force push

Configuration

Add to .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(npm *)", "Bash(git log*)"],
    "deny": ["Bash(rm -rf*)"]
  }
}