AGENTS.md · diff

git:20260206.74b6ded to git:20261106.254db97

35 added, 57 removed. Audit A to A.

# AGENTS.md: AI Assistant Entry Point

This is your entry point for understanding and working with the Interpretive Orchestration project.

---

## What's in This Repository

+ One plugin, with a manifest for each agent tool that can install it:

```

repo-root/

│

├── AGENTS.md # ← You are here

├── README.md # Human-facing project overview

- │

- ├── plugin/ # Claude Code plugin (ORIGINAL)

- │ ├── CLAUDE.md # Plugin instructions & maintenance guide

- │ ├── ARCHITECTURE.md # Full architecture reference

- │ ├── skills/ # 12 skills (JavaScript)

- │ ├── agents/ # 4 agents (markdown)

- │ ├── commands/ # Commands system

- │ └── hooks/ # JavaScript hooks

- │

- ├── plugin-cowork/ # Claude Desktop/Cowork plugin

- │ ├── README.md # Cowork plugin guide

- │ └── commands/ # 17 qual-* commands (flat structure)

+ ├── CITATION.cff # How to cite the work

+ ├── .claude-plugin/marketplace.json # Claude Code and Copilot CLI marketplace

+ ├── .agents/plugins/marketplace.json # Codex marketplace

+ ├── kimi.plugin.json # Kimi Code manifest

│

- └── plugin-kimi/ # Kimi CLI plugin (COMPLETE)

- ├── README.md # Kimi plugin user guide

- ├── AGENTS.md # Agent reference

- ├── CHANGELOG.md # Version history & credits

- ├── .agents/

- │ ├── skills/ # 12 skills for Kimi (Python)

- │ ├── agents/ # 5 YAML files (4 agents + router)

- │ └── contexts/ # 3 stage contexts

- ├── examples/ # Sample project

- └── tests/ # Test suites

+ └── plugin/ # The plugin

+ ├── CLAUDE.md # Maintenance guide and agent instructions

+ ├── ARCHITECTURE.md # Full architecture reference

+ ├── skills/ # 17 qual-* commands + 12 skills (JavaScript scripts)

+ ├── agents/ # 4 agents (markdown)

+ ├── hooks/ # hooks.json + run-hook.js adapter + hook scripts

+ └── tests/ # node tests/run-tests.js

```

+ The Python port for the archived kimi-cli (`plugin-kimi/`) was removed in 0.3.0. It is still in the `v0.2.5` tag.

---

## Project Overview

**Interpretive Orchestration** is a methodology for human-AI partnership in qualitative research.

### The 3-Stage Sandwich

```

Stage 1 (Foundation): Human codes manually (10+ docs)

↓

Stage 2 (Collaboration): Human + AI partnership

↓

Stage 3 (Synthesis): Human synthesizes with AI dialogue

```

### The 5 Non-Negotiables

1. **Human interpretive authority** — AI never decides final meanings

2. **Stage 1 requirement** — Manual foundation before AI collaboration

3. **Visible reasoning** — 4-stage process mandatory

4. **Reflexivity embedded** — Regular prompted reflection

5. **Partnership not automation** — Transform thinking, don't replace

### The 4 Agents

| Agent | Stage | Role |

|-------|-------|------|

| @stage1-listener | Stage 1 | Thinking partner, never codes |

| @dialogical-coder | Stage 2 | 4-stage visible reasoning |

| @research-configurator | Stage 2 | Technical orchestration |

| @scholarly-companion | Stage 3 | Theoretical dialogue |

---

## For Different Tasks

### I want to understand the project

1. This file (overview, architecture, non-negotiables)

2. `plugin/ARCHITECTURE.md` (full technical architecture)

- 3. `plugin-kimi/examples/sample-research-project/README.md` (workflow example)

+ 3. `plugin/examples/tutorial-quickstart/README.md` (workflow example)

### I need to update the Claude Code plugin

1. `plugin/CLAUDE.md` (instructions, skill list, maintenance guide)

2. `plugin/ARCHITECTURE.md` (architecture reference)

- ### I need to update the Kimi plugin

- 1. `plugin-kimi/FUTURE-PARITY-GUIDE.md` (porting process)

- 2. `plugin/CLAUDE.md` → "Kimi CLI Plugin Maintenance" section (conventions, doc checklist)

- 3. `plugin-kimi/CHANGELOG.md` (version history)

- ### I want to port to another platform

+ ### I need to support another platform

- 1. `plugin-kimi/FUTURE-PARITY-GUIDE.md` (porting patterns: JS→Python mapping)

- 2. `plugin-kimi/.agents/skills/qual-shared/scripts/` (reference implementation)

- 3. Use `plugin-kimi/` as your template

+ 1. `plugin/CLAUDE.md` → "Plugin Marketplace Structure" and "Other platforms"

+ 2. Keep one plugin folder; add a manifest, not a port

### I need to fix a bug

- 1. Check if the bug exists in Claude version too (`plugin/`)

- 2. Fix in the affected plugin(s)

- 3. Run tests: `bun test` (Claude) or `python3 plugin-kimi/tests/test_integration.py` (Kimi)

+ 1. Fix it in `plugin/`

+ 2. Run tests: `bun run test` (or `node plugin/tests/run-tests.js`)

+ 3. Validate: `claude plugin validate .` and `claude plugin validate plugin`

---

## Current Status

| Component | Status |

|-----------|--------|

- | **Claude Code Plugin** | 12 skills, maintained |

- | **Kimi CLI Plugin** | 12 skills, production-ready |

- | **Cowork Plugin** | 17 commands, maintained |

- | **Feature Parity** | 12/12 skills across Claude & Kimi |

- | **Tests** | All passing |

+ | **Plugin** | 0.3.0: 17 commands (as skills), 12 skills, 4 agents, 6 hooks |

+ | **Claude Code** | Full support, including hooks |

+ | **Codex, Copilot CLI, Kimi Code** | Installable; see `plugin/CLAUDE.md` → "Other platforms" for what works |

+ | **Tests** | `node plugin/tests/run-tests.js` |

---

## Key Documents

| Document | Purpose |

|----------|---------|

- | `plugin/CLAUDE.md` | Claude plugin instructions & Kimi maintenance guide |

+ | `plugin/CLAUDE.md` | Maintenance guide and agent instructions |

| `plugin/ARCHITECTURE.md` | Full architecture reference |

- | `plugin-kimi/README.md` | Kimi plugin user guide |

- | `plugin-kimi/AGENTS.md` | Agent documentation for Kimi |

- | `plugin-kimi/CHANGELOG.md` | Version history and build credits |

- | `plugin-kimi/FUTURE-PARITY-GUIDE.md` | Maintenance and porting process |

- | `plugin-kimi/MVP-SCOPE.md` | Scope, requirements, known limitations |

- | `plugin-cowork/README.md` | Cowork plugin guide |

+ | `plugin/docs/HOOKS-PHILOSOPHY.md` | Why each hook exists and how it is wired |

+ | `plugin/CHANGELOG.md` | Version history |

---

## Testing

```bash

- # Claude Code plugin

- bun test

- # Kimi CLI plugin (tests run standalone, no pytest required)

- python3 plugin-kimi/tests/test_integration.py

- python3 plugin-kimi/tests/test_end_to_end.py

- python3 plugin-kimi/tests/test_performance.py

+ bun run test # all suites

+ node plugin/tests/test-hooks.js # hooks and the hook adapter

+ claude plugin validate . # marketplace

+ claude plugin validate plugin # plugin

```

---

## Critical Rules

When working on this project:

1. **Never break the 5 non-negotiables** (see above)

2. **Always maintain Stage 1 enforcement**

3. **Keep 4-stage reasoning visible**

4. **Preserve agent personalities**

5. **Run tests before committing changes**

6. **Update documentation with code changes** (see checklist in `plugin/CLAUDE.md`)

---

## Local Development Notes

- If a `workshop-notes/` directory exists locally, it contains additional development context (AI handoff guides, Kimi port artifacts, methodology notes). These are gitignored and not required for working on the project.

+ If a `workshop-notes/` directory exists locally, it contains additional development context (AI handoff guides, methodology notes). These are gitignored and not required for working on the project.

---

*Interpretive Orchestration: Epistemic Partnership System*

- *Built by Xule Lin and Kevin Corley (Imperial College London)*

+ *Built by Xule Lin (SKEMA Business School) and Kevin Corley (Imperial College London)*