guide-integrator

name	guide-integrator
description	Use when a phase command (research/design/implement) needs to load methodology references, online dev-guides, and project playbooks before task work begins. **v4.10.0+: hybrid detection** — a deterministic phase-aware methodology floor + lexical catalog candidates via scripts/dev-guides-detect.sh, plus semantic matches from the guides-matcher agent. Delegates guide fetching to dev-guides-navigator. Loads playbook layers via scripts/playbook-load-deterministic.sh. Cross-references conflicts. Records loaded guide IDs into session_context.json loadedGuides[] to prevent re-loads.
version	5.3.0
user-invocable	false
model	inherit

Guide Integrator

Load development references and integrate into architecture documents. Two sources: plugin methodology refs and online dev-guides (via navigator).

Built-in References (Methodology)

Topic	Reference File
Test-Driven Development	references/tdd-workflow.md
SOLID Principles	references/solid.md
DRY Patterns	references/dry-patterns.md
Library-First/CLI-First	references/library-first.md
Quality Gates	references/quality-gates.md
Purposeful Code	references/purposeful-code.md

Activation

PROACTIVE: Activate at the START of every phase activity — do not wait for explicit request.

Activate when:

• Any Phase 1 activity — load guides for the task's domain before research
• Any Phase 2 activity — load architecture decision guides before design
• Any Phase 3 activity — load security, SDC, JS guides before implementation
• Designing features that match reference topics
• User mentions specific patterns (TDD, SOLID, DRY)
• Architecture drafting for any feature
• Auto-triggered by architecture-drafter agent

Skip if: The relevant guide is already listed in loadedGuides[] — run ${CLAUDE_PLUGIN_ROOT}/scripts/session-context-read.sh (Bash) and parse its JSON .loadedGuides for the per-workspace session (see "Record Loaded Guide" below). The conversation context is an unreliable fallback; the file is the source of truth.

Methodology Floor (Plugin References)

The plugin methodology references load by a phase-aware floor, not by keyword matching. ${CLAUDE_PLUGIN_ROOT}/scripts/dev-guides-detect.sh <task_folder> --phase <research|design|implement|complete> emits the floor deterministically — every task at a phase loads these regardless of task content:

Phase	Methodology floor
Research	references/tdd-workflow.md, references/solid.md, references/dry-patterns.md
Design (and later)	the above + references/library-first.md
Implement / Complete	the above + references/quality-gates.md

Guide IDs: plugin:tdd-workflow, plugin:solid, plugin:dry-patterns, plugin:library-first, plugin:quality-gates.

Why a floor, not keywords (v4.10.0+). The v4.0.0 keyword table ("test" → tdd-workflow, "quality" → quality-gates, …) produced spurious matches and could be silently zeroed by an agent claiming "none matched." The phase floor is deterministic and unconditional — Stage 1 (dev-guides-detect.sh) always emits it; the guides-matcher agent (Stage 2) can add domain guides and re-rank but can never remove the floor. That is the anti-bypass guarantee.

Domain dev-guides (framework, language, and design-system topics) are NOT in the floor — they come from Stage 1 catalog_candidates[] plus the Stage-2 guides-matcher agent. See the phase commands' "Dev-guides preflight" step.

Workflow

1. Load Plugin References (Methodology)

From the phase floor emitted by dev-guides-detect.sh:

1. Check loadedGuides[] (see "Record Loaded Guide" below). If the ID (e.g. plugin:solid) is already present, skip.
2. Identify which methodology references the phase floor includes (see Methodology Floor above).
3. Read each floor reference file
4. Record the guide ID via the snippet in "Record Loaded Guide"
5. Extract patterns relevant to current task

2. Delegate Online Guides to Navigator

For domain-specific architecture decisions, invoke the dev-guides-navigator skill with the task keywords. For each topic the navigator returns:

1. Check loadedGuides[]. If the topic ID (e.g. <framework>/forms/form-validation) is already present, skip re-fetching.
2. Fetch via the navigator (which handles its own content caching of llms.txt).
3. Record the topic ID via the snippet in "Record Loaded Guide".

The navigator handles:

• Hash-based caching of llms.txt (no redundant fetches)
• Topic matching with KG metadata disambiguation
• Routing to the correct guide via topic index.md
• Fetching the specific guide content

Do NOT fetch llms.txt or dev-guides URLs directly — the navigator does this with caching and disambiguation.

2b. Record Loaded Guide

For every guide actually loaded (methodology or dev-guide), append its ID to the per-workspace session_context.json loadedGuides[]. Idempotent — skip if already present.

Guide ID conventions:

• Plugin methodology refs: plugin:<basename> (e.g. plugin:solid, plugin:tdd-workflow)
• Dev-guides topics: the topic path as returned by dev-guides-navigator (e.g. <framework>/forms/form-validation, design-systems/<topic>)

Run this after each successful load, substituting {GUIDE_ID}:

GUIDE_ID="{GUIDE_ID}"
[ -n "$GUIDE_ID" ] || exit 0   # guard against empty IDs polluting the list
WORKSPACE_HASH=$(echo -n "$PWD" | md5sum | cut -d' ' -f1)
SESS_FILE=~/.claude/ai-dev-assistant/sessions/${WORKSPACE_HASH}.json
[ -s "$SESS_FILE" ] || exit 0
jq --arg g "$GUIDE_ID" \
  'if (.loadedGuides // []) | index($g) then . else .loadedGuides = ((.loadedGuides // []) + [$g]) end' \
  "$SESS_FILE" > "$SESS_FILE.tmp" && mv "$SESS_FILE.tmp" "$SESS_FILE"

If session_context.json does not yet exist, skip silently — the next framework command will create it via scripts/session-context-write.sh and future loads will be recorded.

3. Extract Applicable Patterns

From all loaded sources (methodology refs + navigator results), identify:

• Patterns that apply to current feature
• Checklists to follow
• Warnings or anti-patterns
• Recommended approaches

4. Add to Architecture

Use Edit to add references section to architecture file:

## Development References

### Plugin References (Methodology)
| Reference | Key Patterns |
|-----------|--------------|
| solid.md | Single responsibility, DI |
| library-first.md | Service → Form → Route |
| tdd-workflow.md | Red-Green-Refactor |

### Dev-Guides Applied (via Navigator)
| Topic | Key Decisions |
|-------|--------------|
| `<framework>/forms/` | Config-backed form vs request form |
| `<framework>/data/` | Persistent record vs configuration record |

### Enforcement Points
| Phase | Principle | Source |
|-------|-----------|--------|
| Design | Library-First | references/library-first.md |
| Design | SOLID | references/solid.md |
| Design | Framework patterns | dev-guides (via navigator) |
| Implement | TDD | references/tdd-workflow.md |
| Implement | DRY | references/dry-patterns.md |
| Complete | Quality Gates | references/quality-gates.md |
| Complete | Security | dev-guides `<framework>/security/` |

5. Summarize

Tell user what was integrated from each source: plugin methodology and dev-guides topics.

6. Load Playbook (v3.15.0+)

After loading methodology refs and dev-guides topics, load the project's playbook layers:

6a. Read project state

Run ${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh "<project_folder>" (Bash) and parse .playbookSets[], .userPlaybook, .userPlaybookState, and .playbookResolutions[].

6b-c. Deterministic load (v4.0.0+)

As of v4.0.0, the playbook load step is delegated to a single deterministic script that handles both shipped sets AND local playbook in one invocation:

"${CLAUDE_PLUGIN_ROOT}/scripts/playbook-load-deterministic.sh" "<project_folder>"

The script reads project_state.md via project-state-read.sh, resolves playbookSets[] (records intent — actual fetch from dev-guides-navigator happens here in step 6b for guide CONTENT), loads userPlaybook via playbook-read.sh, and emits a structured JSON with playbook_sets_loaded, user_playbook_loaded, plays_by_section count map. The integrator stores the JSON as <task>/_playbook-load.json audit file (per references/gate-audit-schema.md v1.0). This replaces the previous agent-mediated load.

For each set in playbook_sets_loaded[]: delegate to dev-guides-navigator to fetch individual guide pages relevant to the current task domain. Record each loaded guide ID via the snippet in the "Record loaded guide IDs" section. Track loaded guide titles + summaries for cross-reference.

6d. Detect conflicts

Cross-reference local plays vs shipped guides AND multi-set vs multi-set:

• Local-vs-shipped: when a local play's title or section topic matches a shipped guide's topic AND their normative content differs → emit a conflict (winner: local).
• Multi-set contradiction: when 2+ shipped sets address the same topic with different normative content → emit a conflict (winner determined by playbookResolutions[] if present, else null and surface to user).

Emit conflicts[] in the return JSON:

{
  "loaded_guides": ["plugin:solid", "<framework>/forms/config-forms"],
  "loaded_playbook_sets": ["<framework>/best-practices/camoa"],
  "loaded_local_playbook": { "path": "/abs/path", "play_count": 19 },
  "conflicts": [
    {
      "topic": "font-sizing",
      "type": "local-vs-shipped",
      "playbook_set_citation": {...},
      "local_citation": {...},
      "winner": "local"
    }
  ]
}

6e. Surface conflicts once per session per topic

For each conflict in conflicts[]:

1. Check session-context state (a per-session "surfaced topics" set) to see if this topic was already surfaced.
2. If not surfaced: print one-line surface to the user (e.g. "Playbook conflict on font-sizing: shipped says X, local says Y. Local wins.").
3. Record to <project>/.claude/playbook-conflicts.log via playbook-conflicts-write.sh.
4. Mark topic surfaced for this session.

For multi-set contradictions WITHOUT a stored resolution: prompt the user to pick (1/2/cancel); on choice, persist to project_state.md **Playbook Resolutions:** map.

For local-vs-shipped: no prompt; precedence rule applies; just announce.

6f. Record loaded playbook IDs

Record each loaded shipped-set guide and the local playbook into loadedGuides[] per the "Record loaded guide IDs" section. Local playbook ID convention: local:userPlaybook:<basename>.

Mid-phase guide checks

The preflight at phase start loads the methodology floor + the domain guides matched from the artifacts that exist then. Work uncovers more as it proceeds — an existing third-party library chosen during research, an API reached for while drafting architecture, a pattern that surfaces mid-implementation.

Standing instruction: before writing code or architecture that uses a framework API, an existing third-party library, or a pattern that is not already represented in loadedGuides[], do a catalog lookup via the dev-guides-navigator skill for that topic. If a guide exists, load and apply it; record its ID per "Record Loaded Guide". If none exists, proceed.

This is not a gate and never blocks — it is a discipline that keeps guide coverage tracking the work as it actually unfolds, instead of freezing at whatever the phase-start artifacts implied. Cheap because loadedGuides[] dedups: a topic already loaded is a no-op. Apply it whenever the work turns to a domain the preflight could not have seen coming.

Reference Locations

Type	Location
Plugin references (methodology)	{plugin_path}/references/*.md
Dev-guides (online)	Via dev-guides-navigator skill

Stop Points

STOP and ask user:

• Before adding patterns that conflict with existing architecture