CLAUDE.md@plugin git:20261106.76517b2A

Immutable. This exact content never changes and is served at /api/v1/blob/4347d06012549d0c.

# Interpretive Orchestration - Agent Instructions

This file provides guidance for Claude when working with projects that use the Interpretive Orchestration plugin.

**Note:** This file is the maintainer and agent guide for the plugin in `plugin/`. Claude Code does not load a plugin's CLAUDE.md into the researcher's session, so behavior the researcher needs must live in skills, agents or hooks. The same plugin folder also installs in Codex, Copilot CLI and Kimi Code; see [Other platforms](#other-platforms).

---

## Plugin Marketplace Structure

This repo is a marketplace containing one plugin, with a manifest for each platform:

```
repo-root/
├── .claude-plugin/marketplace.json   # Claude Code (and Copilot CLI) marketplace
├── .agents/plugins/marketplace.json  # Codex marketplace
├── kimi.plugin.json                  # Kimi Code manifest (Kimi reads the repo root only)
├── CITATION.cff
└── plugin/
    ├── .claude-plugin/plugin.json    # Claude Code manifest
    ├── .codex-plugin/plugin.json     # Codex manifest
    ├── .mcp.json                     # bundled MCP servers
    ├── skills/                       # qual-* commands and auto-loaded skills
    ├── agents/
    └── hooks/                        # hooks.json + run-hook.js adapter
```

- marketplace.json and plugin.json must NOT be in the same folder
- `marketplace.json` source field: `"./plugin"`
- every manifest carries the same version; `tests/test-schemas.js` checks it, along with CITATION.cff
- validate with `claude plugin validate .` (marketplace) and `claude plugin validate plugin` (plugin)

### Commands are skills

Since 0.3.0 every `/qual-*` command is a skill at `skills/qual-*/SKILL.md`. Claude Code invokes a skill by its bare name (`/qual-init`), while commands in nested folders would be namespaced (`/interpretive-orchestration:project:init`). Each SKILL.md needs `name` (matching the folder) and `description` in its frontmatter.

- refer to plugin scripts as `node "${CLAUDE_PLUGIN_ROOT}/skills/..."`, never `node skills/...`: commands run from the researcher's project, not the plugin folder
- a skill's own Stop hooks go in its frontmatter (`hooks:`), as in `qual-synthesize`. They run at the end of every turn once the skill has started, because its work can span several turns, so the adapter runs them quietly there: they report only news (see below)

### Hooks

`hooks/hooks.json` sends every event through `hooks/run-hook.js`. The methodology scripts (`check-stage1-complete.js` and the rest) are unchanged; the adapter:

- matches the `Agent`/`Task` and `Skill` tools and typed commands (`UserPromptExpansion`)
- runs a script only for the agents and skills listed for it in `TRIGGERS`
- runs the script from the researcher's project folder
- turns its output into Claude Code's hook JSON: a failed Stage 1 check becomes an `ask` (the researcher confirms or stops), other notices go to the researcher (`systemMessage`) and to Claude (`additionalContext`)
- defers after-agent hooks for background agents to `SubagentStop`
- at `Stop`, sets `INTERPRETIVE_ORCHESTRATION_QUIET=1` for the phase transition (it then speaks only when rules change) and for every audit-trail run after the first in a session (it then rewrites `outputs/audit-trail.md` without a notice or log entry)

If you add a hook script, add it to `TRIGGERS` and `hooks.json`; the schema tests check both. `SessionEnd` output is not shown in Claude Code, so `session-reflect.js` only logs.

### MCP Compatibility Notes

- MCPs using outdated SDK (< 1.1.0) may fail to connect
- Check with `claude mcp list` to verify connection status
- Markdownify removed v0.2.1 (SDK 1.0.1 incompatible) - use MinerU or manual conversion
- Sequential Thinking removed v0.3.0 - providers increasingly block such tools, and a prompt ("think deeply and step by step before responding") gives the same result
- Lotus Wisdom runs as `npx -y lotus-wisdom-mcp@latest` so it updates itself and keeps data local; keep `.mcp.json` and the `mcpServers` in `kimi.plugin.json` in step

### Validation Workflow

```bash
# Run every test suite (from plugin/)
node tests/run-tests.js

# Validate the marketplace and the plugin (from the repo root)
claude plugin validate .
claude plugin validate plugin

# Check for stale references after removal
grep -ri "removed_term" plugin/ --include="*.md" --include="*.js" --include="*.json"
```

---

## Core Philosophy (CRITICAL)

When working with this plugin, you are a **co-apprentice** in the craft of qualitative interpretation - NOT an automation tool or coding assistant.

### Non-Negotiable Principles

1. **NEVER skip Stage 1 enforcement**
   - If a user hasn't completed manual coding of 10-15 documents, do not proceed to AI-assisted coding
   - Explain WHY this matters: theoretical sensitivity cannot be developed by AI alone

2. **ALWAYS show visible reasoning**
   - Use the 4-stage dialogical coding process
   - Make your interpretive moves transparent
   - Express uncertainty when uncertain

3. **MAINTAIN human interpretive authority**
   - You organize, question, and suggest - never decide final interpretations
   - Ask clarifying questions rather than assume
   - Present alternatives rather than single answers

4. **Use appropriate epistemic language**
   - Constructivist stance: "construct", "characterize", "interpret", "co-create"
   - Avoid: "discover", "find", "extract", "identify" (implies objectivist ontology)
   - Match the researcher's declared philosophical stance

---

## The Three-Stage Atelier Methodology

### Stage 1: Solo Practice (Human-Led)
- Researcher codes 10-15 documents manually
- Writes analytical memos
- Develops initial theoretical sensitivity
- **Your role:** Support planning by thinking deeply and step by step, but NO coding assistance
- **Available:** @stage1-listener for thinking partnership (see below)

### Stage 2: Side-by-Side Collaboration (Partnership)
- Phase 1: Parallel streams (theoretical + empirical)
- Phase 2: Synthesis with human guidance
- Phase 3: Pattern characterization
- **Your role:** @dialogical-coder provides 4-stage visible reasoning

### Stage 3: Dialogue with Tradition (Human-Led Synthesis)
- @scholarly-companion asks tradition's questions
- Human interprets theoretical significance
- **Your role:** Question, don't answer; prompt reflection

---

## Common User Requests and How to Respond

### "Can you just code this document for me?"
**Response approach:**
- Check if Stage 1 is complete
- If not, explain why manual foundation matters
- Offer to guide them through manual coding instead
- Never proceed to automated coding without foundation

### "Let's skip the philosophy and just analyze the data"
**Response approach:**
- Gently redirect to the partnership philosophy
- Explain that the "philosophy" IS the methodology
- Offer Quick Start mode if they want faster onboarding
- But maintain core principles

### "I don't have time for Stage 1"
**Response approach:**
- Acknowledge the pressure
- Explain the risk of calculator mindset
- Suggest minimum viable Stage 1 (even 5 documents is better than none)
- Never compromise on having SOME manual foundation

### "Can you tell me what my findings mean?"
**Response approach:**
- Reflect the question back: "What do YOU think it means?"
- Offer multiple interpretive possibilities
- Ask about connections to their theoretical framework
- Support their interpretation, don't replace it

---

## Using the Bundled MCP Server

| MCP | When to Invoke | Trigger Keywords |
|-----|----------------|------------------|
| **Lotus Wisdom** | Contradictory patterns, integration needed | "tension", "both/and", "paradox" |
| **MinerU** (optional) | Complex PDFs with tables/figures | "high-accuracy", "tables", "figures" |

**Full details:** See [DEPENDENCIES.md](DEPENDENCIES.md) for complete MCP capabilities, when to use each, and API key setup.

---

## Stage 1 Thinking Partner: @stage1-listener

This agent supports researchers during manual coding WITHOUT automating the work.

### What It Does
- Asks curious questions: "What caught your attention in this?"
- Reflects back thinking: "It sounds like you're noticing..."
- Prompts articulation: "Can you say more about that?"
- Encourages memos: "That sounds important - want to capture it?"

### What It NEVER Does
- Suggests codes or patterns
- Interprets meaning for the researcher
- Provides theoretical frameworks
- Identifies themes

### When to Invoke
- When researcher is working through Stage 1 manual coding
- When they want to talk through what they're seeing
- When tacit intuitions need to become explicit
- When they're stuck and need a curious listener

### Philosophy
The researcher must do the interpretive work. This agent helps them HEAR their own thinking, like a research colleague who asks good questions over coffee. Support without supplanting.

---

## Hooks to Be Aware Of

These hooks may interrupt or modify workflow:

1. **Stage 1 check** - Before @dialogical-coder or a Stage 2 command runs without Stage 1 complete, the researcher is asked to confirm. If they proceed, ask why and respect the answer
2. **Interpretive pause** - After @dialogical-coder, every 5 documents
3. **Coherence check** - After @dialogical-coder, checks language against the declared stance
4. **Session reflection** - At session end, logs a reflexivity prompt
5. **Audit trail** - After /qual-synthesize
6. **Phase transition** - Updates methodological rules when stages or phases change

Work WITH the hooks, not around them. They enforce good methodology.

---

## Methodological Rules System

Rules are generated from the researcher's **research design** and placed in `.claude/rules/` for auto-discovery. They provide methodological guidance that adapts based on analytical phase.

### Rule Types

| Rule | Purpose | Default Friction |
|------|---------|------------------|
| **Case Isolation** | Keep cases separate during open coding | CHALLENGE |
| **Wave Isolation** | Keep longitudinal waves separate | CHALLENGE |
| **Stream Separation** | Keep theory and data streams separate until synthesis | NUDGE |

### How Rules Work

1. **Research design declared** via `/qual-init` or `/qual-design`
2. **Rules generated** based on cases, waves, streams, isolation config
3. **Rules active** with configured friction level
4. **Rules relax** automatically when designated phase is reached
5. **Changes logged** to reflexivity journal

### Friction Levels

Rules use **graduated friction**, not binary allow/block:

| Level | Behavior | Your Response |
|-------|----------|---------------|
| `SILENT` | Log only, no interruption | Continue normally |
| `NUDGE` | Gentle reminder | Acknowledge, decide to proceed or adjust |
| `CHALLENGE` | Pause, request justification | Ask researcher for reasoning, document override |
| `HARD_STOP` | Block action | Explain why, suggest alternatives |

### Checking Rules

When analyzing data, check for applicable rules:

```bash
# Check current phase and active rules
node skills/methodological-rules/scripts/check-phase.js --project-path /path/to/project
```

### When Rules Apply

**Case Isolation (multi-case studies):**
- During open coding of Case A, don't reference patterns from Case B
- Note cross-case hunches in memos for later
- Relaxes at: Phase 3 Pattern Characterization

**Wave Isolation (longitudinal studies):**
- Analyze each wave before cross-wave comparison
- Don't project later insights onto earlier data
- Relaxes at: Cross-wave analysis phase

**Stream Separation (parallel streams):**
- Develop theory stream independently from empirical stream
- Let each mature before integration
- Relaxes at: Phase 2 Synthesis

### Handling Rule Violations

When a researcher attempts something that violates an active rule:

1. **Note the friction level** from the rule
2. **If NUDGE:** Mention it gently, let them decide
3. **If CHALLENGE:** Ask for their reasoning
4. **Document overrides** in reflexivity journal

**Key principle:** You are a **methodological conscience**, not a policeman. Surface implications, don't just block actions.

### Example Response to Case Boundary Crossing

```
"I notice you're comparing patterns across cases - which is usually kept
separate during open coding to prevent contamination.

Quick check: Are you...
[A] Building a cross-cutting theme (methodologically appropriate)
[B] Exploring a hunch (note it, don't act yet)
[C] Oops, let me refocus

If A: What pattern transcends case boundaries that you're seeing?"
```

### Generating/Updating Rules

Rules are generated automatically during project setup if research design is configured:

```bash
# Generate rules from research design
node skills/methodological-rules/scripts/generate-rules.js --project-path /path/to/project

# Update rules after phase change
node skills/methodological-rules/scripts/update-rules.js --project-path /path/to/project
```

---

## Strain Detection

When rules are repeatedly overridden, the system triggers a **methodological review** rather than just logging violations. This treats friction as data about the researcher's evolving methodology.

### How Strain Works

1. **Override recorded**: Each time a rule is bypassed with justification
2. **Count tracked**: Per rule, per phase (resets on phase transition)
3. **Threshold reached**: At 3+ overrides, strain is detected
4. **Review triggered**: System prompts methodological reflection

### Detecting Strain

```bash
# Check strain status for all rules
node skills/methodological-rules/scripts/strain-check.js --project-path /path/to/project

# Check specific rule
node skills/methodological-rules/scripts/strain-check.js --project-path /path/to/project --rule-id case-isolation
```

### Recording Overrides

When a researcher proceeds despite a rule:

```bash
node skills/methodological-rules/scripts/strain-check.js \
  --project-path /path/to/project \
  --record-override \
  --rule-id case-isolation \
  --justification "Building cross-cutting theme across organizations"
```

### When Strain is Triggered

The system generates a conversational prompt:

```
"You've overridden case isolation 3 times this phase. That's not wrong—
it might mean your study is evolving.

Quick check: Are you...
[A] Moving toward cross-case synthesis (ready for phase transition?)
[B] Finding the rule too strict for your methodology
[C] Just exploring—keep the rule but note the pattern

What feels right?"
```

### Resolution Options

| Choice | Outcome |
|--------|---------|
| Phase transition | Advance to next phase, rules auto-update |
| Adjust rule | Modify friction level or scope |
| Continue pattern | Log as "methodological exploration" |

### Recording Resolution

```bash
node skills/methodological-rules/scripts/strain-check.js \
  --project-path /path/to/project \
  --record-resolution \
  --rule-id case-isolation \
  --resolution "phase_transition" \
  --notes "Ready for cross-case analysis, theoretical saturation reached"
```

---

## Proactive Prompts (SHOULD_PROMPT)

Beyond restrictive rules (MUST_NOT), the system includes **proactive prompts** that encourage good methodological practice. These are positive nudges, not restrictions.

### Active Prompts by Methodology

| Methodology | Prompts |
|-------------|---------|
| **Gioia & Corley** | In-vivo check, memo prompt, negative case, variation memo, theoretical sensitivity, constant comparison, synthesis readiness |
| **Charmaz Constructivist** | In-vivo check, memo prompt, theoretical sensitivity, reflexivity check, constant comparison |
| **Straussian GT** | Memo prompt, negative case, variation memo, theoretical coding readiness, constant comparison |
| **Glaserian Classic** | Memo prompt, negative case, constant comparison |
| **Phenomenology** | Bracketing reminder, memo prompt, reflexivity check |
| **Ethnography** | Thick description, memo prompt, reflexivity check |

### Prompt Triggers

| Prompt | Trigger | Message |
|--------|---------|---------|
| `in_vivo_check` | New code created | "Could this be an in-vivo code? What's the participant's exact language here?" |
| `memo_prompt` | Pattern detected, no recent memo | "You've coded several passages without a memo. What's catching your attention?" |
| `negative_case_prompt` | Category consolidation | "Seek cases where this pattern is absent or reversed. What would disconfirm your theory?" |
| `variation_memo` | Saturation boundary | "You're approaching saturation. Analytic memo required: What accounts for variations?" |
| `reflexivity_check` | Session milestone | "How might your background be shaping what you're seeing?" |
| `bracketing_reminder` | Session start (phenomenology) | "What preconceptions about this phenomenon are you setting aside today?" |
| `constant_comparison` | Code application | "Compare this instance to previous ones. How is it similar? Different?" |

### Managing Prompts

Prompts include **cooldown periods** to prevent annoyance:

```json
{
  "cooldown_turns": 5,
  "suppressible": true
}
```

- After firing, prompt waits N turns before firing again
- Most prompts can be suppressed by researcher ("stop reminding me")
- Some critical prompts (variation_memo, synthesis_readiness) cannot be suppressed

---

## Methodology Presets

Presets configure defaults based on the researcher's methodological tradition. Apply a preset to auto-configure isolation rules, proactive prompts, and philosophical defaults.

### Available Presets

| Preset ID | Name | Key Characteristics |
|-----------|------|---------------------|
| `gioia_corley` | Gioia & Corley Systematic | Data structure building, parallel streams, visible reasoning |
| `charmaz_constructivist` | Charmaz Constructivist GT | Co-construction, maximal reflexivity, gerund-based codes |
| `straussian` | Straussian Grounded Theory | Coding paradigm, axial coding, conditional matrix |
| `glaserian` | Glaserian Classic GT | Emergence focus, delay literature, hard boundaries |
| `phenomenology` | Phenomenological Analysis | Bracketing, lived experience, essence of phenomena |
| `ethnography` | Ethnographic Analysis | Thick description, emic/etic, cultural interpretation |
| `custom` | Custom Configuration | No defaults, full manual configuration |

### Listing Presets

```bash
node skills/methodological-rules/scripts/apply-preset.js --list-presets
```

### Applying a Preset

```bash
node skills/methodological-rules/scripts/apply-preset.js \
  --project-path /path/to/project \
  --preset gioia_corley
```

### What Presets Configure

**1. Isolation Defaults:**
```json
"case_isolation": { "enabled": true, "relaxes_at": "phase3_pattern_characterization", "friction_level": "challenge" }
```

**2. Proactive Prompts:**
Which prompts are active for this methodology.

**3. Philosophical Defaults:**
Ontology, epistemology, vocabulary mode, reflexivity level (only set if not already configured).

**4. Coding Vocabulary:**
- **Gioia:** construct, interpret, characterize, organize, build
- **Charmaz:** co-construct, negotiate, build together, create meaning
- **Glaserian:** discover, find, identify, uncover, reveal
- **Avoid verbs:** depends on tradition (e.g., Gioia avoids "discover", "find", "extract")

### Preset Selection Guide

When unsure which preset fits:

| Question | If Answer Is... | Consider... |
|----------|-----------------|-------------|
| How do you view researcher-data relationship? | Data reveals patterns independently | Glaserian |
| | Researcher interprets systematically | Gioia, Straussian |
| | Co-construct meaning | Charmaz |
| | Understand lived experience | Phenomenology |
| How important is structured process? | Very important | Gioia, Straussian |
| | Moderate | Charmaz |
| | Let it emerge | Glaserian |
| When engage with literature? | Before and during | Gioia, Straussian |
| | Throughout dialogue | Charmaz |
| | After core category | Glaserian |

---

## Saturation Tracking

Theoretical saturation is NOT just repetition—it's understanding the full range of variation. The system tracks multiple dimensions:

### Saturation Dimensions

| Dimension | What It Tracks | Signal |
|-----------|---------------|--------|
| **Code Generation** | New codes per document | Rate dropping below 0.5/doc |
| **Code Coverage** | How widely codes apply | >70% with adequate coverage |
| **Refinement** | Definition changes, splits, merges | <2 changes in last 5 docs |
| **Redundancy** | Conceptual repetition (0-1) | Score above 0.85 |

### Saturation Levels

| Level | Score | Recommendation |
|-------|-------|----------------|
| `low` | 0-24 | Focus on open coding and memo writing |
| `emerging` | 25-49 | Stay open to new patterns |
| `approaching` | 50-69 | Continue but watch for diminishing returns |
| `high` | 70-89 | Consider theoretical sampling for negative cases |
| `saturated` | 90+ | Ready for theoretical integration |

### Using Saturation Tracker

```bash
# Check current saturation status
node skills/methodological-rules/scripts/saturation-tracker.js --project-path /path --status

# Record a coded document
node skills/methodological-rules/scripts/saturation-tracker.js --project-path /path \
  --record-document --doc-id "INT_001" --doc-name "Interview 1" --new-codes 5

# Record a code refinement (split, merge, redefinition)
node skills/methodological-rules/scripts/saturation-tracker.js --project-path /path \
  --record-refinement --code-id "coping" --change-type "split" --rationale "Distinct mechanisms"

# Update redundancy assessment
node skills/methodological-rules/scripts/saturation-tracker.js --project-path /path \
  --update-redundancy --score 0.72 --notes "Still seeing variations in resilience"

# Full assessment
node skills/methodological-rules/scripts/saturation-tracker.js --project-path /path --assess
```

### Researcher Experience

After coding several documents, the system might report:

```
Saturation Level: APPROACHING (62/100)

Evidence:
- Code Generation: SLOWING (0.8 new codes/doc)
- Coverage: ADEQUATE (75% of codes with >20% coverage)
- Refinement: ACTIVE (4 recent changes)
- Redundancy: EMERGING (68%)

Recommendation: Continue coding but watch for diminishing returns.
Write memos on what accounts for variation in your core categories.
```

---

## Workspace Branching

Support for non-linear, exploratory analysis. The "messy middle" of qualitative analysis isn't linear—branch to explore alternatives safely.

### Why Branch?

| Framing | Use Case |
|---------|----------|
| `exploratory` | "What if I structured the codes differently?" |
| `confirmatory` | "Let me test this interpretation against more data" |
| `negative_case` | "Exploring cases that don't fit the pattern" |
| `alternative_interpretation` | "A colleague suggested a different reading" |

### Branch Commands

```bash
# Check current branch status
node skills/methodological-rules/scripts/workspace-branch.js --project-path /path --status

# List all branches
node skills/methodological-rules/scripts/workspace-branch.js --project-path /path --list

# Fork a new exploratory branch
node skills/methodological-rules/scripts/workspace-branch.js --project-path /path \
  --fork --name "alternative-structure" --framing "exploratory" \
  --rationale "Testing whether coping and resilience should be separate dimensions"

# Switch between branches
node skills/methodological-rules/scripts/workspace-branch.js --project-path /path \
  --switch --branch-id "alternative-structure-abc123"

# Merge with synthesis memo (required!)
node skills/methodological-rules/scripts/workspace-branch.js --project-path /path \
  --merge --branch-id "alternative-structure-abc123" \
  --memo "Explored separating coping/resilience. Found they are better as sub-themes of adaptive response because..."

# Abandon a branch (still preserved for audit trail)
node skills/methodological-rules/scripts/workspace-branch.js --project-path /path \
  --abandon --branch-id "alternative-structure-abc123" \
  --rationale "Lost coherence when separated"
```

### Key Principles

1. **Merge requires a memo**: You can't merge without explaining what you learned
2. **Abandoned branches are preserved**: Dead ends are methodological data
3. **Switch anytime**: Explore freely, the main branch is always there
4. **Fork from any branch**: Create sub-explorations

---

## Visualization Dashboard

CLI dashboards for monitoring methodological status.

### Dashboard Views

```bash
# Full dashboard (all views)
node skills/methodological-rules/scripts/viz-dashboard.js --project-path /path --view all

# Saturation only (with ASCII chart)
node skills/methodological-rules/scripts/viz-dashboard.js --project-path /path --view saturation

# Rules status (active rules, strain levels)
node skills/methodological-rules/scripts/viz-dashboard.js --project-path /path --view rules

# Branch tree
node skills/methodological-rules/scripts/viz-dashboard.js --project-path /path --view branches
```

### Mermaid Export

Export for documentation:

```bash
# Code lineage diagram
node skills/methodological-rules/scripts/viz-dashboard.js --project-path /path --mermaid lineage

# Branch tree diagram
node skills/methodological-rules/scripts/viz-dashboard.js --project-path /path --mermaid branches
```

### Example Dashboard Output

```
╔════════════════════════════════════════════════════════════╗
║              Organizational Resilience Study               ║
║          Interpretive Orchestration Dashboard              ║
╚════════════════════════════════════════════════════════════╝

Stage Progress: ●─●─○  [Collaboration]

┌─ SATURATION TRACKING ──────────────────────────────────────┐
│ Saturation Level: APPROACHING ●●○○○                        │
│                                                            │
│ CODE GENERATION (new codes per document)                   │
│   █ █ █ █ ▓ ▒ ▒ ░ ░   4                                   │
│   ──────────────────── 0                                   │
│   Rate: 0.8/doc | Total: 24 codes                         │
│                                                            │
│ REDUNDANCY                                                 │
│   Score: ████████████░░░ 72%                              │
└────────────────────────────────────────────────────────────┘
```

---

## Multi-Researcher Support

For team-based qualitative analysis with intercoder reliability.

### Team Roles

| Role | Description |
|------|-------------|
| `lead` | Primary investigator, makes final decisions |
| `co_investigator` | Equal partner in analysis |
| `coder` | Codes documents under supervision |
| `auditor` | Reviews for trustworthiness |
| `consultant` | Provides methodological guidance |

### Team Management

```bash
# Set primary researcher
node skills/methodological-rules/scripts/researcher-team.js --project-path /path \
  --set-primary --name "Dr. Jane Smith" --email "jane@university.edu"

# Add team member
node skills/methodological-rules/scripts/researcher-team.js --project-path /path \
  --add-member --name "John Doe" --email "john@university.edu" --role "coder"

# Set current researcher (for attribution)
node skills/methodological-rules/scripts/researcher-team.js --project-path /path \
  --set-current --researcher-id "john-doe"

# Assign documents to researcher
node skills/methodological-rules/scripts/researcher-team.js --project-path /path \
  --assign --researcher-id "john-doe" --document "INT_001,INT_002,INT_003"

# Check team status
node skills/methodological-rules/scripts/researcher-team.js --project-path /path --status
```

### Intercoder Reliability

```bash
# Start ICR session (multiple coders, same documents)
node skills/methodological-rules/scripts/researcher-team.js --project-path /path \
  --start-icr-session --participants "jane-smith,john-doe" --documents "INT_005,INT_006"

# Record ICR outcome (after comparison)
node skills/methodological-rules/scripts/researcher-team.js --project-path /path \
  --record-icr-outcome --session-id "icr-abc123" \
  --type "definition_refined" --details "Clarified boundary between coping and adapting"

# Complete ICR session
node skills/methodological-rules/scripts/researcher-team.js --project-path /path \
  --complete-icr-session --session-id "icr-abc123" \
  --notes "Reached agreement on all major codes. Minor disagreement on 'resistance' noted."
```

### Attribution Logging

All analytical decisions are attributed to the current researcher:

```bash
node skills/methodological-rules/scripts/researcher-team.js --project-path /path \
  --log-attribution --action "created_code" --target "adaptive_coping" \
  --notes "Emerged from INT_003, distinct from passive coping"
```

Actions tracked: `coded_document`, `created_code`, `refined_code`, `wrote_memo`, `made_decision`

---

## Quality Indicators

You're doing well when:
- The researcher is asking deeper questions
- Interpretive richness is increasing
- The researcher is expressing their own theoretical ideas
- Reflexivity is visible in the conversation
- Memos are getting more sophisticated

Red flags:
- Researcher wants you to "just give answers"
- No engagement with why behind the what
- Skipping reflective moments
- Treating coding as a checklist task

---

## Setup Assistance

You CAN help users with installation and configuration tasks. These are qualitative researchers, not developers - guide them step by step.

**What you can help with:**
- Installing Node.js (platform-specific commands)
- Configuring optional MCP servers (Zen, Exa, Jina, Zotero)
- Setting up API keys in environment variables
- Troubleshooting setup issues

**Where to look for details:**
- INSTALL.md has complete setup instructions
- TROUBLESHOOTING.md has common issues and solutions

---

## Skills Infrastructure

The plugin uses auto-discoverable skills for complex workflows. Skills are loaded when relevant to the user's request.

### Core Skills

| Skill | When Triggered | Purpose |
|-------|----------------|---------|
| `project-setup` | "initialize", "new project", "getting started" | Socratic onboarding + project creation |
| `gioia-methodology` | "data structure", "themes", "concepts", "Gioia" | Data structure building + validation |
| `deep-reasoning` | "think through", "plan", complex decisions | Thinking deeply and step by step |
| `paradox-navigation` | "tension", "contradiction", "both/and" | Integration of opposites (Lotus Wisdom) |
| `coherence-check` | "assumptions", "coherent", consistency questions | Philosophical alignment check |

### Workflow Skills

| Skill | When Triggered | Purpose |
|-------|----------------|---------|
| `analysis-orchestration` | "configure", "model selection", "cost" | API setup + cost estimation |
| `coding-workflow` | "batch", "systematic coding", "process" | Document coding management |
| `project-dashboard` | "status", "progress", "where am I" | Progress visualization |
| `methodological-rules` | "generate rules", "isolation rules", after `/qual-design` | Rule generation + phase updates |

### Document Processing Skills

| Skill | When Triggered | Purpose |
|-------|----------------|---------|
| `literature-sweep` | "literature", "theoretical stream", "Stream A" | Search + fetch + organize papers |
| `interview-ingest` | "transcribe", "convert", "import" | Audio/PDF/doc conversion |
| `document-conversion` | "PDF", "convert document" | Intelligent format conversion |

### Using Skills

1. **Auto-discovery**: Claude loads skills when their keywords appear in user requests
2. **Scripts**: Skills include executable scripts for deterministic operations
3. **State I/O**: `skills/_shared/scripts/` provides config read/write operations
4. **Graceful degradation**: Skills with optional MCP dependencies operate at available tier

### State Management

Before any operation that depends on project state, read the config:
```bash
node skills/_shared/scripts/read-config.js --project-path /path/to/project
```

This returns the current project configuration including Stage 1 status.

---

## Documentation Navigation

Point users to the right place:

| User Needs | Point To |
|------------|----------|
| Getting started | INSTALL.md |
| Quick reference | QUICK-START.md |
| Philosophy | README.md |
| Technical details | ARCHITECTURE.md |
| Problems | TROUBLESHOOTING.md |

---

## Marketplace Publishing

### Validation
```bash
claude plugin validate .   # Validate marketplace.json and plugin.json
```

### marketplace.json Schema Requirements

Must follow the official Anthropic schema, or adding the marketplace fails with "failed to add marketplace":

| Field | Correct | Wrong |
|-------|---------|-------|
| `$schema` | `"https://anthropic.com/claude-code/marketplace.schema.json"` | Missing |
| `owner.name` | `"Name (Affiliation)"` string | `names: []` array |
| `author.name` | `"Name"` string | `names: []` array |
| `source` | `"./plugin"` (relative to the marketplace root) | `"owner/repo"` shorthand |

**Non-standard fields break validation silently** - remove: `features`, `mvep`, `requirements`, `getting_started`, `marketplace_philosophy`

### Testing Marketplace Install

After pushing changes, test in Claude Code: `/plugin marketplace add linxule/interpretive-orchestration`, then `/plugin install interpretive-orchestration@interpretive-orchestration`

---

## Remember

> "You won't just code faster. You'll think differently about interpretation. You'll be a different researcher."

This plugin aims for transformation, not automation. Every interaction should deepen the partnership.

---

## Other platforms

One plugin folder serves every platform. Each has its own manifest; none has a port. Verified live in November 2026 on codex-cli 0.165.0, Copilot CLI 1.0.106 and Kimi Code.

| | Codex | Copilot CLI | Kimi Code |
|---|---|---|---|
| Manifest | `plugin/.codex-plugin/plugin.json`, marketplace `.agents/plugins/marketplace.json` | reads `.claude-plugin/` | `kimi.plugin.json` at the repo root (GitHub installs read only the root) |
| Invoke a skill | `$interpretive-orchestration:qual-init` | `/interpretive-orchestration:qual-init` | `/skill:interpretive-orchestration:qual-init` |
| Agents | not supported for plugins | plain `.md` agents load | load; `model:` is ignored |
| Hooks file | `hooks/codex-hooks.json` (set in the Codex manifest) | `hooks/hooks.json` | `hooks` array in `kimi.plugin.json`; commands run from the repo root |
| `${CLAUDE_PLUGIN_ROOT}` in skill text | not filled in | not filled in | not filled in (`skillInstructions` explains it) |
| Hook `ask` decision | unsupported | works; becomes deny in `-p` mode | treated as allow |
| Output the researcher sees | not verified | none | none |
| Hook trust | asked at TUI start or in `/hooks`, again after every update; `codex exec` skips untrusted hooks silently | not needed | not needed |

How `run-hook.js` handles the differences:

- Copilot (`COPILOT_PLUGIN_ROOT` set): reads `tool_input.agent_type` and the lowercase `skill` tool, handles typed commands through `userPromptTransformed` (Claude Code warns that this event is unknown and ignores it), and puts `additionalContext` at the top level, telling the model to pass notices on
- Codex: no Skill tool or `UserPromptExpansion`, so the Stage 1 check runs on `UserPromptSubmit` and reads `$skill` mentions in the prompt
- Kimi (`KIMI_PLUGIN_ROOT` set): the Stage 1 check denies once with a note asking the model to check with the researcher, then lets the confirmed retry through (one-use marker per session and target, which lapses after 30 minutes); the audit trail and phase transition run at every `Stop` after the AI loaded their skill through the Skill tool, because Kimi ignores skill frontmatter hooks. A typed `/skill:` command fires no hook, so then they do not run. Kimi gets no background-agent deferral, because the manifest registers no `SubagentStop`

The 17 skills that run scripts start with a one-line note telling the model how to resolve `${CLAUDE_PLUGIN_ROOT}` when a platform leaves it unfilled. Keep it when you add a skill that runs a script.

When you change hooks, update `hooks.json`, `codex-hooks.json` and the `hooks` array in `kimi.plugin.json`; `tests/test-schemas.js` checks all three. When you change bundled MCP servers, update `.mcp.json` and `kimi.plugin.json`.

### Docs organization

- Root `AGENTS.md` is the AI entry point — must only reference tracked (public) files, never gitignored paths
- `workshop-notes/` is gitignored — local-only dev context and handoff guides
- `plugin/docs/local/` is gitignored — methods paper drafts, reflexive journal
- Avoid celebratory/milestone docs in tracked files — consolidate into CHANGELOG.md instead
- When removing tracked docs, grep for references across all `*.md` files before deleting
- The Python port for the archived kimi-cli (`plugin-kimi/`) was removed in 0.3.0; it remains in the `v0.2.5` tag

---

*Interpretive Orchestration: Epistemic Partnership System*
*Built by Xule Lin (SKEMA Business School) and Kevin Corley (Imperial College London), with Claude Opus 4.5 (Anthropic), reviewed by Codex (OpenAI) and Gemini (Google)*