Repository Context Checker
Purpose
Prevent developers from starting planning work in code repositories by detecting context mismatches and providing guidance on where work should happen.
Repository Type Detection
Brain Repository Indicators
A repository is a brain repo if it exhibits these characteristics:
Directory Structure:
- Has
specs/ or specs-in-progress/ directory
- Has
roadmap/ or product-roadmap/ directory
- Has
patterns/ or architecture/ directory
- Has
docs/ with coordination or strategy documents
- Filename patterns:
*.adr.md, *.spec.md, decision-*.md
Plugin Configuration (from .claude/settings.json):
- 20+ plugins enabled
- Contains planning agents:
v-architect, v-tech-lead, v-commerce-pm, v-platform-pm
- Contains
v-9d or v-discovery workflows
- Contains multiple domain plugins (3+)
- Repository name contains:
-brain suffix (e.g., prism-brain, beam-brain)
README/CLAUDE.md Indicators:
- Describes coordination, planning, or cross-functional work
- Mentions "spec", "architecture", "strategy", "roadmap"
- Links to other repositories
Code Repository Indicators
A repository is a code repo if it exhibits these characteristics:
Directory Structure:
- Has
src/, lib/, main/, components/, app/ directory
- Has production code:
.ts, .tsx, .java, .py, .go files
- Has deployment configs:
Dockerfile, k8s/, .github/workflows/
- Has
tsconfig.json, package.json, pom.xml, setup.py
- Filename patterns: service name (e.g.,
BeamService, VioletDashboard)
Plugin Configuration (from .claude/settings.json):
- 8-15 plugins enabled
- NO planning agents:
v-architect, v-tech-lead, v-*-pm should not be present
- NO product workflows:
v-9d, v-discovery, v-gates
- ONE stack plugin:
v-java-spring, v-typescript-react, etc.
- ONE domain plugin: The service implements
- Repository name pattern:
{Name}Service or {Name}Dashboard
README/CLAUDE.md Indicators:
- Describes implementation, testing, deployment
- Links to brain repo or product spec repo
- Has sections like "Setup", "Development", "Testing", "Deployment"
Task Type Detection
Planning Task Keywords
The following words and phrases indicate planning work (belongs in brain repo):
Decision-making indicators:
- "should we", "do we want", "trade-off", "pros and cons"
- "architecture", "design", "redesign"
- "strategic", "vision", "roadmap"
- "why are we", "why did we", "rationale for"
Specification indicators:
- "spec", "specification", "requirement"
- "ADR", "architecture decision record"
- "user story", "acceptance criteria"
- "what should", "what will"
Product management indicators:
- "feature request", "feature proposal"
- "customer request", "user feedback"
- "product manager input", "PM approval"
- "cross-product", "impact analysis"
Approval/Review indicators:
- "architect approval", "tech lead review"
- "design review", "architecture review"
- "should be approved by"
Implementation Task Keywords
The following words and phrases indicate implementation work (can be in code repo):
Code change indicators:
- "implement", "add", "remove", "modify", "change"
- "bug fix", "fix the bug", "fix issue #"
- "refactor", "optimize", "clean up"
- "test", "add test", "test coverage"
Reference indicators:
- "from spec", "per ADR", "from requirements"
- "known root cause", "root cause: "
- "existing code", "existing function"
Scope indicators:
- "this function", "this service", "this component"
- "limited scope", "scoped change"
- "no architectural impact"
Mixed Task Indicators
Some tasks require both brain and code repos:
Investigation → Implementation pattern:
- "why is X slow?" (brain: analysis) → "implement the optimization" (code: impl)
- "why is the API failing?" (brain: root cause) → "fix the bug" (code: impl)
- "can we do X?" (brain: feasibility) → "implement it" (code: impl)
Decision → Implementation pattern:
- "should we refactor Y?" (brain: decision) → "here's the refactored code" (code: impl)
- "architecture for X?" (brain: design) → "implement following the design" (code: impl)
Warning Triggers
Severity: HIGH (Strong Warning)
Warn when:
- In code repo + multiple planning keywords + no spec reference
- In code repo + asking "should we" or "why should we"
- In code repo + "redesign", "rewrite", "new feature" without existing spec
- In code repo + asking for architect or PM input
- Planning agents (v-architect, v-tech-lead) activated in code repo
Severity: MEDIUM (Informational)
Inform when:
- In code repo + asking design questions with some spec reference
- In code repo + refactoring with architectural impact
- In brain repo + implementation-focused questions (can proceed but FYI)
Severity: LOW (Suggestion)
Suggest when:
- Task could benefit from other repo context
- Related specs or decisions exist in brain repo
Decision Logic
IF in_code_repo:
IF task_type = "planning":
IF has_spec_reference:
severity = MEDIUM
ELSE:
severity = HIGH
ELSE IF task_type = "implementation":
severity = NONE
ELSE IF task_type = "mixed":
severity = MEDIUM (planning phase)
ELSE IF in_brain_repo:
IF task_type = "implementation":
severity = LOW (suggestion to move to code repo)
ELSE:
severity = NONE
ELSE:
severity = UNKNOWN (ambiguous repo type)
Action Recommendations
Brain Repo → Code Repo Flow
When planning is complete, recommend:
- Create specs in brain repo
- Get architect/tech-lead approval in brain repo
- Switch to code repo with approved spec
- Reference spec or ADR in code repo work
Code Repo → Brain Repo Flow
When planning is needed, recommend:
- Switch to brain repo
- Create specs/ADRs there
- Get approvals there
- Return to code repo when ready to implement
Related Documentation
/v-plugins-context command: Runs this detection and provides guidance
violet-ai-plugins/CLAUDE.md: "Brain Repos vs Code Repos" section
examples/README.md: Decision tree for choosing repository type
v-plugins/knowledge/plugin-management.md: Plugin selection rules