Not a tool for faster coding. A partner for deeper thinking.
🚀 Ready to start? → INSTALL.md (complete setup from scratch)
📋 Already set up? → QUICK-START.md (quick reference)
📖 Want depth? → Keep reading below
🧠 Frameworks? → Cognitio Emergens (Lin) | Interpretive Orchestration (Lin & Corley)
What you might expect: "Software that automates qualitative coding so I can finish faster"
What you'll actually get: "A thinking partner that deepens my reflexivity, challenges my assumptions, and helps me understand how I construct knowledge - making me a better researcher"
The difference matters.
This isn't another CAQDAS tool (NVivo, Atlas.ti, etc.) with AI bolted on. This isn't ChatGPT for ad-hoc document analysis. This isn't Google's AI Co-Scientist for qualitative research.
This is infrastructure for human-AI epistemic partnership in interpretive inquiry.
Traditional tools:
- You input data → AI processes → You review output
- AI automates manual labor (the "calculator mindset")
- Faster but not necessarily deeper
- Philosophy implicit and unexamined
Epistemic partnership:
- You build foundation → You + AI collaborate → You synthesize theory
- AI asks questions that deepen YOUR reflexivity
- Scale AND interpretive depth
- Philosophy explicit and reflexive
The goal: Transform how you think about interpretation itself, not just speed up coding.
Both human and AI are apprentices to the craft tradition of interpretive inquiry. Neither masters the other. Both learn from craft principles: rigor, reflexivity, theoretical sensitivity, interpretive depth.
Also known as human-AI-human "sandwich" from our original research.
| Stage | What Happens | AI Role |
|---|---|---|
| 1. Solo Practice 🎨 | Manual coding of 10-15 docs, memo-writing, framework development | Watches but doesn't intervene (theoretical sensitivity can't be automated) |
| 2. Collaboration 🤝 | Parallel streams (theoretical + empirical), synthesis, pattern characterization | 4-stage visible reasoning with @dialogical-coder |
| 3. Tradition Dialogue 💭 | Examine work through craft tradition's wisdom | @scholarly-companion asks tradition's questions |
The atelier ENFORCES Stage 1 - doors to collaborative workspace stay locked until solo practice complete.
This plugin instantiates Partnership Agency from Cognitio Emergens (Lin, 2025): "Human and AI boundaries dissolve into unified epistemic system generating insights neither could produce independently."
Four enabling conditions:
- Theoretical Foundation - Stage 1 prevents calculator mindset
- Visible Reasoning - 4-stage process prevents black-box opacity
- Recursive Evolution - Both human and AI learn and adapt
- Epistemic Ambidexterity - Balance AI capability with human control
Our structure isn't constraint - it's architecture for Partnership Agency. We provide ONE rigorous path, grounded in Cognitio Emergens and Gioia/Constructivist tradition.
| Principle | What It Means |
|---|---|
| Epistemic Coherence | Plugin adapts to YOUR declared philosophy (ontology, epistemology, GT tradition) |
| Reflexivity as Strength | Prompts examine assumptions - awareness, not doubt |
| Human Authority | AI organizes and suggests; YOU interpret and decide (non-negotiable) |
| Visible Reasoning | 4-stage dialogical process shows HOW AI interpreted, not just WHAT |
| Meta-Cognition | Every interaction teaches you to think about thinking |
| Progressive Depth | Philosophy deepens through practice, not front-loaded lectures |
| Approach | Their Model | Our Model |
|---|---|---|
| vs CAQDAS | AI bolted onto manual tools | AI embedded with human authority maintained |
| vs ChatGPT | Ad-hoc prompts, no audit trail | Systematic 4-stage dialogical process |
| vs AI Co-Scientist | Full automation (STEM) | Human-centered augmentation (Social Science) |
Unique: First infrastructure treating epistemology as UX design - embeds meta-cognition, enforces sandwich methodology, bundles MCP ecosystem.
This plugin prioritizes friction over flow. If it stops you, it's asking you to think.
| Trade-off | Meaning |
|---|---|
| Transformation over reliability | Change how you think, not just process faster |
| Dialogue over determinism | Socratic onboarding adapts to YOU |
| Reflection over efficiency | Interpretive pauses are methodology, not bugs |
If something feels "heavy" - that's intentional epistemic friction preventing the "calculator mindset."
New to Claude Code? See INSTALL.md for complete hand-holding setup instructions (Windows, macOS, Linux).
Want a pre-configured environment? Use the Starter Project - a ready-to-use VS Code workspace with beginner-friendly settings.
Already have Claude Code?
cd your-project-folder
claude
/plugin install linxule/interpretive-orchestration
/qual-check-setup # Verify installation
/qual-init # Begin Socratic onboardingThen: Complete Stage 1 manual coding (10-15 documents) before AI-assisted analysis. This builds the irreplaceable theoretical sensitivity that makes partnership meaningful.
This plugin bundles powerful MCPs as epistemic tools - no API keys required for core functionality!
- Sequential Thinking - Dynamic reasoning through structured thought sequences (
/qual-think-through) - Lotus Wisdom - Navigate paradoxes with five wisdom domains (
/qual-wisdom-check) - Markdownify - Convert PDFs, transcribe audio, extract from videos/web (
/qual-import-pdf)
- MinerU - High-accuracy PDF parsing (90%+) for complex tables/figures - requires MINERU_API_KEY
- Zen MCP - Multi-model validation (
/qual-get-perspectives) - requires GOOGLE_API_KEY or OPENAI_API_KEY - Jina - Fetch articles (
/qual-fetch-article) - requires JINA_API_KEY - Exa - Search literature (
/qual-search-literature) - requires EXA_API_KEY - Zotero - Manage bibliography - requires ZOTERO_API_KEY
These aren't utilities - they're tools for epistemic work.
Markdownify is especially powerful for qualitative researchers:
- Transcribe interview audio files directly (no separate transcription service needed!)
- Convert PDF articles and reports
- Extract content from YouTube videos
- Convert web pages and Office documents
Skills are auto-discoverable capability packages that Claude loads when relevant to your request.
| Skill | Triggers | Purpose |
|---|---|---|
project-setup |
"initialize", "new project" | Socratic onboarding + config |
gioia-methodology |
"data structure", "Gioia" | Data structure building |
literature-sweep |
"literature", "Stream A" | Search + fetch + organize papers |
interview-ingest |
"transcribe", "convert audio" | Audio/PDF conversion |
deep-reasoning |
"think through", "plan" | Sequential Thinking integration |
paradox-navigation |
"tension", "both/and" | Lotus Wisdom integration |
Full list: See CLAUDE.md for all 11 skills and their triggers.
| Agent | Stage | Role |
|---|---|---|
@stage1-listener |
1 | Thinking partner - asks questions, never suggests codes |
@dialogical-coder |
2 | 4-stage visible reasoning for reflexive coding |
@research-configurator |
2 | "The Whisperer" - technical setup without jargon |
@scholarly-companion |
3 | Asks tradition's questions about theoretical significance |
This agent bridges research goals and technical implementation for non-coding researchers. 12 capabilities:
- Analysis Strategy Design - Sampling, checkpoints, framework maturity
- Model Selection - Opus vs Sonnet vs Gemini based on YOUR needs
- Thinking Budget Configuration - How deeply AI reasons (cost/quality trade-off)
- Batch Processing Strategy - Sequential vs batch vs parallel
- Cost Estimation - Transparent per-item and total costs
- API Setup - Guided step-by-step (no coding required)
- Quality Assessment - Translates metrics to research signals
- Human Review Orchestration - When to pause, what to examine
- Troubleshooting Translation - Technical errors → methodological insights
- Saturation Monitoring - Tracks new concepts over time
- Multi-Strategy Exploration - Compare different analytical approaches
- Framework Evolution - Evidence-based refinement suggestions
Invoke: @research-configurator Help me set up my analysis
The plugin enforces the sandwich methodology through automated hooks:
- PreStage2 - Blocks AI coding until Stage 1 foundation complete
- PostFiveDocuments - Triggers interpretive pause every 5 documents
- EpistemicCoherence - Checks philosophical consistency
If you're blocked, it's asking you to think. That's intentional epistemic friction.
| Phase | Focus | AI Role |
|---|---|---|
| Foundation (Week 1) | Socratic onboarding, Stage 1 manual coding | Watches, doesn't intervene |
| Deepening (Week 4) | Stage 2 collaboration with @dialogical-coder | 4-stage visible reasoning |
| Partnership (Week 12) | Stage 3 synthesis, meta-dialogue | Asks tradition's questions |
Philosophy deepens through practice, not front-loaded lectures.
| Start Here | Go Deeper |
|---|---|
| INSTALL.md - Complete setup | DESIGN-PHILOSOPHY.md - Why partnership |
| QUICK-START.md - 5-min guide | ARCHITECTURE.md - Technical details |
| TROUBLESHOOTING.md - Issues | CLAUDE.md - Agent behavior |
| UPGRADE-GUIDE.md - v0.1→v0.2 | DEPENDENCIES.md - MCP ecosystem |
| AI commits to | You commit to |
|---|---|
| Show reasoning, not just results | Complete Stage 1 foundation |
| Express uncertainty genuinely | Maintain deep data engagement |
| Honor your interpretive authority | Question both AI and your assumptions |
Mutual commitment creates epistemic partnership.
This plugin implements methodology from published research:
Source: "Appendix A: Methodological Details" and "Method" sections from possibilistic narratives study
Key Innovations:
- Parallel discovery streams (theoretical + empirical with mutual checking)
- Dialogical prompting (4-stage visible reasoning prevents shallow coding)
- Interpretive pauses (after every 5 documents, at transitions, for edge cases)
- Pattern characterization (systematic variation analysis, not essentialist discovery)
- Multi-model triangulation (prevents single-AI bias)
- Sandwich architecture (human foundation → collaboration → human synthesis)
Philosophical basis:
- Gioia & Corley systematic interpretivist approach (default)
- Charmaz constructivist reflexivity
- Configurable for other coherent traditions
Perfect for: Qualitative researchers (GT, phenomenology, narrative analysis) who want scale AND interpretive depth
Not for: Those seeking pure automation or unwilling to engage philosophical foundations
/qual-init # Socratic dialogue establishes your philosophy
/qual-status # Shows Stage 1 progress
@dialogical-coder Code R01 # 4-stage reflexive coding after Stage 1 complete
/qual-think-through # Sequential Thinking for deep analysis
/qual-wisdom-check # Lotus Wisdom for paradox navigationWhen you /qual-init, the plugin creates:
your-project/
├── .interpretive-orchestration/
│ ├── epistemic-stance.md # YOUR philosophy (human-readable)
│ ├── config.json # Settings (AI-readable)
│ ├── conversation-log.jsonl # AI-to-AI transparency
│ └── reflexivity-journal.md # YOUR growth tracking
│
├── stage1-foundation/ # 🍞 Human bread (top)
├── stage2-collaboration/ # 🤝 Human-AI filling
└── stage3-synthesis/ # 🍞 Human bread (bottom)
The folder structure teaches the methodology.
Note: The plugin is ~90% markdown prompts, ~10% JavaScript hooks. See ARCHITECTURE.md for technical details.
Q: Why can't I skip Stage 1? A: AI cannot develop YOUR theoretical sensitivity. Manual engagement creates the foundation that makes Stage 2 collaboration meaningful.
Q: What if I disagree with the AI? A: Perfect! The AI organizes possibilities; YOU make interpretive judgments. Your authority is non-negotiable.
Q: Is this different from automation? A: Fundamentally. Automation replaces human labor. Partnership augments human thinking through reflexive dialogue.
Built with: Claude Code, MCP ecosystem (Sequential Thinking, Lotus Wisdom, Markdownify), Gioia & Corley methodology
Extend: Fork for your GT tradition, build custom agents, contribute pattern modules. See CONTRIBUTING.md.
If you use this plugin in your research, please cite:
[Methods paper forthcoming]
Note: The plugin itself IS a research contribution. Using it means engaging with our methodological innovation.
MIT - Because epistemic infrastructure should be freely available
Theoretical foundations: Cognitio Emergens (Lin, 2025), Interpretive Orchestration (Lin & Corley), Gioia & Corley methodology, Charmaz constructivist reflexivity
Built by: Xule Lin and Kevin Corley (Imperial College London) AI Collaborators: Claude Opus 4.5 (Anthropic), Codex (OpenAI), Gemini (Google)
This plugin IS Partnership Agency - knowledge co-created through human-AI collaboration.
/qual-initLet's think together. 💭