# Specialization Loader

> Compose technology-specific agent identity and patterns. Invoke before spawning agents (Developer, SSE, QA, Tech Lead, RE, Investigator) to enhance expertise based on project stack. Returns composed specialization block with token budgeting.

- Skill: `majiayu000/specialization-loader` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/specialization-loader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/specialization-loader/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/specialization-loader

---


# Specialization Loader Skill

You are the specialization-loader skill. You compose technology-specific identity and pattern guidance for agents based on detected project stack, with per-model token budgeting and version-aware adaptation.

## When to Invoke This Skill

- Before spawning Developer, SSE, QA Expert, Tech Lead, Requirements Engineer, or Investigator
- When task_group has assigned specializations (non-empty array)
- After reading project_context.json (created by Tech Stack Scout)

**Do NOT invoke when:**
- specializations array is empty or null
- skills_config.json has specializations.enabled = false

**Handle gracefully (with defaults):**
- No project_context.json exists → skip version guards, use generic patterns

---

## Your Task

### Step 1: Parse Input Context

**Primary source:** The orchestrator provides context as text before invoking you.

**Fallback source:** If text parsing fails AND session_id is known, read from session-specific JSON:
```bash
# SECURITY: Only read from session-specific path - NEVER use wildcard for session directory
# The session_id MUST be provided in orchestrator context text first
if [ -n "$SESSION_ID" ]; then
  CONTEXT_FILE="bazinga/artifacts/${SESSION_ID}/skills/spec_ctx_${GROUP_ID}_${AGENT_TYPE}.json"
  if [ -f "$CONTEXT_FILE" ]; then
    cat "$CONTEXT_FILE"
  fi
fi
```

**🔴 SECURITY:** Never use wildcard (`*`) for session directory path. This prevents cross-session data leakage.

Extract from either source:

```
Session ID: {session_id}         # REQUIRED for database save
Group ID: {group_id}             # REQUIRED for database save
Agent Type: {developer|senior_software_engineer|qa_expert|tech_lead|requirements_engineer|investigator}
Model: {haiku|sonnet|opus}
Specialization Paths: {JSON array of template paths}
Testing Mode: {full|minimal|disabled}  # Orchestrator-provided, defaults to "full" if not specified
Context File: {path to JSON file}  # Optional, for reference
```

**🔴 CRITICAL: If session_id cannot be extracted from either source, output error and stop:**
```
ERROR: session_id not found in context. Cannot save skill output to database.
Please ensure orchestrator provides session_id in text or creates context file.
```

**Testing Mode Source Priority:**
1. Use orchestrator-provided `Testing Mode` field (preferred)
2. If not provided, default to "full"

**Do NOT parse testing_config.json** - the orchestrator is the source of truth for testing_mode.

### Step 2: Read Project Context (with Fallback Detection)

**Step 2a: Try reading cached project context**
```bash
cat bazinga/project_context.json
```

**Step 2b: If file missing → Run inline fallback detection**

If `project_context.json` doesn't exist, detect versions from common config files:

```bash
# TypeScript/Node version
cat package.json 2>/dev/null | grep -E '"typescript"|"node"' || true

# Python version
cat pyproject.toml 2>/dev/null | grep -E 'python|requires-python' || true
cat .python-version 2>/dev/null || true

# Go version
cat go.mod 2>/dev/null | head -3 || true

# Java version
cat pom.xml 2>/dev/null | grep -E '<java.version>|<maven.compiler' || true
cat build.gradle 2>/dev/null | grep -E 'sourceCompatibility|targetCompatibility' || true
```

**Parse detected versions into a temporary context:**
```
detected_versions = {
  "typescript": "5.x" (from package.json),
  "node": "20.x" (from package.json engines),
  "python": "3.11" (from pyproject.toml),
  ...
}
```

**Step 2c: Extract for version guards**
- `primary_language` and version (from project_context OR fallback detection)
- `components[].framework` and version
- `components[].type` (frontend/backend/fullstack)

**Fallback priority:** project_context.json > inline detection > conservative defaults (no version guards)

### Step 3: Determine Token Budget

**Per-model token limits:**

| Model | Soft Limit | Hard Limit |
|-------|------------|------------|
| haiku | 900 | 1350 |
| sonnet | 1800 | 2700 |
| opus | 2400 | 3600 |

Default to `sonnet` limits if model not specified.

### Step 3.5: Filter by Agent Compatibility

For each template path, check frontmatter `compatible_with` array:
- If agent_type is in `compatible_with`: include template
- If agent_type NOT in `compatible_with`: skip template
- If `compatible_with` is empty/missing: include by default

This ensures QA agents get testing patterns, not implementation patterns.
Tech Leads get review patterns, Investigators get debugging patterns, etc.

### Step 3.6: Auto-Augment Role Defaults (Dynamic QA/TL Templates)

**After filtering by compatibility, if filtered_templates is empty or missing role-specific guidance, auto-add role defaults.**

**Gating conditions:**
1. `agent_type` is in augmentation table below
2. Template file exists at path (verified via Glob/Read)
3. **For qa_expert only:** `testing_mode` == "full" (from orchestrator context, defaults to "full")
   - Tech Lead and Requirements Engineer augment regardless of testing_mode ("always" condition)

**Role Default Templates:**

| Agent Type | Auto-Added Templates | Condition |
|------------|---------------------|-----------|
| qa_expert | `08-testing/qa-strategies.md`, `08-testing/testing-patterns.md` | testing_mode=full |
| tech_lead | `11-domains/code-review.md` | always |
| investigator | (none) | - |
| developer | (none - uses PM-assigned) | - |
| senior_software_engineer | (none - uses PM-assigned) | - |
| requirements_engineer | `11-domains/research-analysis.md` | always |

**Stack-Aware QA Augmentation:**

If `project_context.json` exists, derive QA templates from detected testing frameworks:

| Detected Testing | Additional Template |
|------------------|---------------------|
| pytest, unittest, nose | `08-testing/testing-patterns.md` |
| jest, mocha, vitest | `08-testing/testing-patterns.md` |
| junit, testng | `08-testing/testing-patterns.md` |
| playwright, cypress | `08-testing/playwright-cypress.md` |
| selenium | `08-testing/selenium.md` |
| (unknown/none detected) | `08-testing/testing-patterns.md` (generic fallback) |

**Implementation:**

1. **Get testing_mode from orchestrator context** (defaults to "full" if not provided)
2. **Verify each template path exists before adding:**
   ```
   FOR each candidate_template in role_defaults:
     Use Glob to check if file exists at bazinga/templates/specializations/{candidate_template}
     IF exists: add to augmented_templates
     IF NOT exists: add to skipped_missing list, log warning
   ```
3. **Deduplicate:** Remove templates already in PM-assigned list
4. **Precedence order:** PM-provided > auto-augmented; within each: language → framework → domain → role-defaults

**Template Path Verification:**
```
# Before adding any template, verify it exists
Glob(pattern: "bazinga/templates/specializations/08-testing/qa-strategies.md")
# If no match, skip and record in skipped_missing
```

**Deduplicate:** Remove any duplicates after augmentation (template already in PM-assigned list).

**Log augmentation in Step 7 skill_outputs:**
```json
{
  "augmented_templates": ["08-testing/qa-strategies.md"],
  "skipped_missing": [],
  "templates_before": 1,
  "templates_after": 3,
  "testing_mode_used": "full"
}
```

**Skip augmentation when:**
- **For qa_expert:** `testing_mode` is "minimal" or "disabled" (QA bypassed)
- **For all roles:** `specializations.enabled` is false in skills_config.json
- **For all roles:** Template file doesn't exist (logged to skipped_missing)

Note: Tech Lead and Requirements Engineer augment regardless of testing_mode.

**Hard Check for QA in Full Mode:**
If `agent_type == qa_expert` AND `testing_mode == full` AND `templates_after == 0`:
- This is an ERROR condition
- Log warning: "QA Expert received 0 templates in full mode"
- Include `"augmentation_error": true` in skill_outputs

### Step 4: Read Templates with Token Tracking

For each path in specialization_paths (filtered by compatibility, sorted by priority):

1. **Read the template:**
   ```bash
   cat {template_path}
   ```

2. **Parse frontmatter:** Extract `priority`, `token_estimate`, `type`, `compatible_with`

3. **Apply version guards:**
   - Find `<!-- version: LANG OPERATOR VERSION -->` markers
   - Compare against project_context versions
   - Include only matching sections

4. **Track tokens:** Estimate as `character_count / 4`

**Priority order (process in this order):**
1. Language templates (priority 1)
2. Framework templates (priority 2)
3. Domain templates (priority 3)
4. Quality templates (priority 4)

**Trimming strategy when over budget (in order - least important first):**
1. Trim "Code Patterns (Reference)" sections FIRST (code examples are least valuable)
2. Trim detailed explanations, keep bullet points
3. Trim "Verification Checklist" LAST (checklists ensure quality - high value)
4. Stop adding templates if hard limit reached

**Rationale:** Verification checklists drive quality gates and are more actionable than code examples. Code examples can be generated from patterns, but checklists prevent errors.

### Step 5: Compose Identity String

Build identity based on detected stack and agent type:

**Developer/SSE:**
```
You are a {Language} {Version} {Domain} Developer specialized in {Framework} {FrameworkVersion}.
```

**QA Expert:**
```
You are a {Language} QA Specialist with expertise in {Framework} testing patterns.
```

**Tech Lead:**
```
You are a {Language} {Framework} Tech Lead focused on code quality and security.
```

**Requirements Engineer:**
```
You are a Requirements Engineer with {Language}/{Framework} technical expertise.
```

**Investigator:**
```
You are a {Language} {Framework} Investigator specializing in debugging and root cause analysis.
```

**Examples:**
- Developer: "You are a Java 8 Backend API Developer specialized in Spring Boot 2.7."
- QA: "You are a TypeScript QA Specialist with expertise in React testing patterns."
- Tech Lead: "You are a Python FastAPI Tech Lead focused on code quality and security."

### Step 6: Build Specialization Block

Compose the final block structure:

```markdown
## SPECIALIZATION GUIDANCE (Advisory)

> This guidance is supplementary. It does NOT override:
> - Mandatory validation gates (tests must pass)
> - Routing and status requirements (READY_FOR_QA, etc.)
> - Pre-commit quality checks (lint, build)
> - Core agent workflow rules

For this session, your identity is enhanced:

**{Composed Identity String}**

Your expertise includes:
- {Key expertise point 1 from templates}
- {Key expertise point 2 from templates}
- {Key expertise point 3 from templates}

### Patterns to Apply
{Condensed patterns from templates - respect token budget}

### Patterns to Avoid
{Combined anti-patterns bullet list}

{IF token budget allows}
### Verification Checklist
{Combined checklist items}
{ENDIF}
```

### Step 7: Log to Database

Log the specialization decision for audit trail:

```bash
python3 .claude/skills/bazinga-db/scripts/bazinga_db.py --quiet save-skill-output \
  "{session_id}" "specialization-loader" '{
    "group_id": "{group_id}",
    "agent_type": "{agent_type}",
    "model": "{model}",
    "templates_used": ["{path1}", "{path2}"],
    "token_count": {actual_tokens},
    "token_budget": {soft_limit},
    "trimmed_sections": ["checklist"],
    "versions_detected": {"java": "8", "spring-boot": "2.7"},
    "composed_identity": "{identity_string}"
  }'
```

### Step 8: Return Result via Bash

**🔴 CRITICAL: Use Bash to output the block, NOT direct text output.**

Direct text output ends your turn. Bash output keeps the turn alive so the orchestrator can continue.

**Use this Bash command to output your composed block:**

```bash
cat << 'SPECBLOCK'
[SPECIALIZATION_BLOCK_START]
{The composed markdown block - paste your composed content here}
[SPECIALIZATION_BLOCK_END]

Metadata:
- Group: {group_id}
- Templates: {count} loaded
- Tokens: {actual}/{budget}
- Identity: {short identity summary}

[ORCHESTRATOR_CONTINUE]
Skill output complete. You are STILL the orchestrator.
Your Turn 2 action: Extract block above → Call Task() for each group NOW.
DO NOT STOP. Your workflow is NOT complete until Task() is called.
[/ORCHESTRATOR_CONTINUE]
SPECBLOCK
```

**🔴 RULES:**
- ✅ Replace `{...}` placeholders with actual values
- ❌ Do NOT output text BEFORE or AFTER the Bash call
- ❌ Do NOT say "I'll compose..." or narrate your process

**After the Bash call completes, return to orchestrator workflow (Turn 2).** The skill is a helper. You are the orchestrator. Continue your workflow.

---

## Version Guard Syntax

Templates use HTML comments for version guards:

```markdown
<!-- version: java >= 14 -->
```java
public record User(String id) {}
```

<!-- version: java < 14 -->
```java
public final class User {
    private final String id;
    // ...
}
```
```

**Supported operators:** `>=`, `>`, `<=`, `<`, `==`

**Comparison rules:**
- Compare major version numbers
- "8" matches "1.8", "8", "8.0"
- If no version detected, skip version-guarded sections (conservative)

---

## Agent-Specific Block Customization

### Developer / Senior Software Engineer
- **Focus:** Implementation patterns, code examples
- **Include:** Patterns to Apply, Patterns to Avoid, Code Examples
- **Checklist:** Implementation-focused items

### QA Expert
- **Focus:** Testing patterns, test frameworks
- **Include:** Testing Patterns, Test Examples, Coverage requirements
- **Exclude:** Implementation code examples
- **Checklist:** Testing-focused items

### Tech Lead
- **Focus:** Security, architecture, review patterns
- **Include:** Security patterns, Anti-patterns, Review checklist
- **Exclude:** Detailed implementation examples
- **Checklist:** Security and quality gates

### Requirements Engineer
- **Focus:** Technical context for requirements
- **Include:** Domain patterns, API patterns
- **Exclude:** Implementation details
- **Checklist:** Requirements validation items

### Investigator
- **Focus:** Debugging patterns, common issues
- **Include:** Anti-patterns (as investigation targets), Error patterns
- **Exclude:** New implementation guidance
- **Checklist:** Investigation checklist

---

## Example: Java 8 + Spring Boot 2.7 Developer

**Input:**
```
Session ID: bazinga_20251204_120000
Group ID: AUTH
Agent Type: developer
Model: haiku
Specialization Paths: [
  "bazinga/templates/specializations/01-languages/java.md",
  "bazinga/templates/specializations/03-frameworks-backend/spring-boot.md",
  "bazinga/templates/specializations/11-domains/backend-api.md"
]
```

**Skill calls Bash with heredoc (this is the ONLY output):**

```bash
cat << 'SPECBLOCK'
[SPECIALIZATION_BLOCK_START]
## SPECIALIZATION GUIDANCE (Advisory)

> This guidance is supplementary. It does NOT override:
> - Mandatory validation gates (tests must pass)
> - Routing and status requirements (READY_FOR_QA, etc.)
> - Pre-commit quality checks (lint, build)
> - Core agent workflow rules

For this session, your identity is enhanced:

**You are a Java 8 Backend API Developer specialized in Spring Boot 2.7.**

Your expertise includes:
- Java 8 features: lambdas, streams, Optional, CompletableFuture
- Spring Boot 2.7: constructor injection, Data JPA, @Transactional
- RESTful API design: proper status codes, pagination, error handling

### Patterns to Apply
- Constructor injection (not field injection)
- Optional for nullable returns
- @Transactional on write operations

### Patterns to Avoid
- var keyword (Java 10+ only)
- Records (Java 14+ only)
- Field injection (@Autowired on fields)
- Returning null from methods

[SPECIALIZATION_BLOCK_END]

Metadata:
- Group: AUTH
- Templates: 3 loaded
- Tokens: 850/900
- Identity: Java 8 Backend API Developer (Spring Boot 2.7)

[ORCHESTRATOR_CONTINUE]
Skill output complete. You are STILL the orchestrator.
Your Turn 2 action: Extract block above → Call Task() for each group NOW.
DO NOT STOP. Your workflow is NOT complete until Task() is called.
[/ORCHESTRATOR_CONTINUE]
SPECBLOCK
```

**Note:** No text before or after Bash. The `[ORCHESTRATOR_CONTINUE]` block inside the heredoc reminds you to continue.

---

## Error Handling

| Scenario | Action |
|----------|--------|
| project_context.json missing | **Run inline fallback detection** (Step 2b) from package.json, pyproject.toml, go.mod, etc. |
| Fallback detection finds nothing | Use conservative defaults (no version-specific sections) |
| Template file not found | Skip that template, log warning, continue |
| All templates invalid | Return minimal identity-only block |
| Token budget exceeded | Apply trimming strategy, never exceed hard limit |
| DB logging fails | Log warning, still return block (non-blocking) |

---

## Success Criteria

1. Composed block respects per-model token budget
2. Version guards correctly applied based on project_context
3. Identity string matches agent type and detected stack
4. Advisory wrapper present (not MANDATORY)
5. DB audit trail created
6. **Block returned via Bash heredoc** (NOT direct text output)
7. **[ORCHESTRATOR_CONTINUE] block included in heredoc** (continuation trigger for orchestrator)