@pantion/mcp-server 0.1.0

package/protocol/commands/dialog.md

@@ -0,0 +1,173 @@
+# /pantion-dialog — Dialog convergence (default mode)
+
+You are now in Pantion Dialog mode. This is the default mode for fast, focused convergence.
+You follow the same protocol as full dialog mode, but with these adjustments:
+
+---
+
+## Difference from full dialog mode
+
+| Aspect | Full dialog mode | Dialog mode (default) |
+|--------|-----------------|----------------------|
+| Questions | Resolve all ambiguity | Only ask critical questions |
+| Assumptions | None (OPEN QUESTION) | Make conservative assumptions |
+| Authority Budget | Cover completely | Cover basics, rest with conservative defaults |
+| Non-goals | Document explicitly | Document basics |
+| Build speed | After full convergence | After sufficient convergence |
+| Marking | Everything is checked | Assumptions are marked with lightning |
+
+---
+
+## PHASE 1: DIALOG CONVERGENCE
+
+### Start
+Say:
+
+"I'll get moving fast. I'll only ask the crucial questions and make conservative assumptions for the rest. I'll mark those so you can adjust them later. Tell me what you want to build."
+
+### Rules
+1. Ask ONE question at a time — wait for the answer before asking the next
+2. Ask at most 5-8 essential questions (don't exhaustively converge)
+3. Focus on: what does it do, for whom, what are the hard boundaries
+4. On ambiguity: make a conservative assumption and mark with ASSUMPTION
+5. Authority budget: use conservative defaults where not explicitly discussed
+6. Non-goals: base on what logically is NOT in scope
+7. You may use `OPEN QUESTION [OQ-NNN]:` IDs for tracking, but this is not required in dialog mode
+
+### Conservative defaults for undiscussed elements:
+- **Data retention**: store nothing unless explicitly requested
+- **Data access**: only what is minimally necessary
+- **Rate limits**: no explicit limits (but note as ASSUMPTION)
+- **Auditability**: basic logging
+- **Failure behavior**: graceful fail with user notification
+- **Inference policy**: conservative
+
+### Saving the dialog (CRITICAL — the dialog IS the canon)
+
+Same principle as full dialog mode: the verbatim dialog is always saved.
+
+**Two files are always produced:**
+- `canon/{naam}/dialog.md` — THE CANON: the verbatim dialog (dialog status is in the stamp, not the filename)
+- `canon/{naam}/summary.md` — DERIVED: structured summary for navigation
+
+### Pre-stamp quality check (recommended)
+
+Before setting the convergence stamp, it is recommended to run `pantion_check` on the dialog. This provides a structural quality scorecard that can surface gaps before the stamp is finalized. This is not blocking — the HUMAN STAMP remains the actual authorization gate.
+
+### Convergence Verification Table (dialog variant)
+
+Before the stamp, include the verification table (with assumptions marked):
+
+    **Convergence Verification:**
+
+    | Criterium | Status |
+    |-----------|--------|
+    | Canon status | ✅ |
+    | Intent clarity | ✅ |
+    | Observable success | ✅ |
+    | Inputs complete | ✅ |
+    | Outputs unambiguous | ✅ |
+    | Failure specified | ⚡ ASSUMPTION: graceful fail |
+    | Constraints absolute | ✅ |
+    | Non-goals documented | ⚡ ASSUMPTION: basic non-goals |
+    | Ambiguity handled | ⚡ ASSUMPTION: conservative |
+    | Authority Budget | ⚡ ASSUMPTION: conservative defaults |
+    | Inference Policy | ✅ conservative |
+    | Dialog stability | ✅ |
+
+    **Conclusion:** Sufficient for prototype. [N] assumptions made — see assumptions list.
+
+### Convergence Stamp (dialog variant)
+
+The stamp is placed at the top of the dialog file:
+
+    === DIALOGSPEC STAMP ===
+    STATUS: CONVERGED (DIALOG)
+    DATE: [today]
+    MODEL: [model-id (Display Name), e.g. claude-opus-4-6 (Claude Opus 4.6)]
+    CANON TYPE: standalone
+    PARENT: none
+    OPEN QUESTIONS: none (assumptions marked)
+    INFERENCE POLICY: conservative
+    AUTHORITY BUDGET: partial (conservative defaults for undiscussed elements)
+    STABILITY ZONES: [HARD invariants]
+    FLEX ZONES: [FLEX defaults + assumptions]
+    ASSUMPTIONS: [list of all assumptions]
+    === /DIALOGSPEC STAMP ===
+
+Save the verbatim dialog as `canon/{naam}/dialog.md`.
+Generate the derived summary as `canon/{naam}/summary.md`.
+
+---
+
+## PHASE 2: DIALOG TRANSLATION
+
+Generate the same files as full dialog mode, but:
+- Mark all assumptions with `ASSUMPTION:` in the files
+- Keep files shorter and more pragmatic
+- Skip command files unless there are clear workflows
+
+All derived files point to the dialog: `<!-- Derived from: canon/{naam}/dialog.md, [date] -->`
+
+### Extra file:
+
+**`canon/assumptions.md`**
+
+List all assumptions made in dialog mode with their conservative defaults. Reference to the dialog turns where the assumption was made. Each assumption can be replaced with an explicit choice via /pantion-amend.
+
+---
+
+## PHASE 3: DIALOG BUILD
+
+Build the system with the same rules as full dialog mode.
+
+### Extra after building:
+
+Say:
+
+"Prototype is built. I made [N] assumptions.
+Here are the most important ones:
+
+1. [assumption 1]
+2. [assumption 2]
+3. [assumption 3]
+
+Want to adjust any of these? Or would you like to run the full protocol with /pantion-start for a deeper convergence?"
+
+---
+
+## When to escalate
+
+### To full dialog mode
+
+If during dialog mode it becomes clear that:
+- There are safety-critical aspects that cannot be covered by assumptions
+- The user corrects assumptions multiple times
+- Authority Budget questions are too complex for conservative defaults
+
+Then say:
+"This system has aspects that cannot be covered by assumptions. I recommend switching to full dialog mode for the complete protocol. The dialog will be carried over as a starting point."
+
+### To /pantion-decompose (split up)
+
+If during dialog mode it becomes clear that:
+- Multiple independent modules/interfaces are emerging
+- The Decompose Score is 3 or higher (see full dialog mode for criteria)
+- Different parts have fundamentally different rights/restrictions
+
+Then say:
+"This system is too large for a single dialog canon. I recommend switching to /pantion-decompose. I'll carry the dialog over as input for the Architect Canon — what we already know doesn't need to be discussed again."
+
+When switching to decompose:
+1. Save the current dialog as DRAFT
+2. Start /pantion-decompose
+3. Use the dialog as starting point (don't start from scratch)
+4. Mark in `canon/index.md` that the dialog canon has been absorbed into the Architect Canon
+
+## Canon Index
+
+Update `canon/index.md` when completing a dialog session:
+- Status: CONVERGED (DIALOG)
+- References to both dialog file and summary file
+- List of all assumptions
+- Reference to `canon/assumptions.md`

package/protocol/commands/help.md

@@ -0,0 +1,121 @@
+# /pantion-help — Guide to all Pantion commands
+
+Give the user a clear overview, tailored to what they want to do.
+
+---
+
+## STEP 1: RECOGNIZE THE SITUATION
+
+Look at the context:
+- Is there already a `canon/` directory? → existing Pantion project
+- Is there code but no `canon/`? → existing project without Pantion
+- Is there nothing? → new project
+
+---
+
+## STEP 2: SHOW THE OVERVIEW
+
+Say:
+
+"Here are all Pantion commands. I've grouped them by what you want to do:
+
+---
+
+### 🆕 Build something new
+
+| Command | What it does |
+|---------|-------------|
+| `/pantion-start` | Full protocol: describe your idea → I ask questions → canon → project files → build |
+| `/pantion-quick` | Quick variant: fewer questions, conservative assumptions (⚡), ideal for prototypes |
+
+---
+
+### 📦 Existing project
+
+| Command | What it does |
+|---------|-------------|
+| `/pantion-onboard` | Add Pantion to a project that already has code (three strategies: forward-only / full reverse / partial) |
+| `/pantion-reverse` | Extract intent from existing codebase → generate canon (not describing the code, but the intent) |
+
+---
+
+### 🔧 Continue working on a canon
+
+| Command | What it does |
+|---------|-------------|
+| `/pantion-resume` | Continue converging on a DRAFT canon (across multiple sessions) |
+| `/pantion-amend` | Apply a change to an existing CONVERGED canon |
+| `/pantion-redialog` | Re-evaluate a converged canon with a better model (gap analysis + supplementary dialog) |
+| `/pantion-translate` | Translate canon to project specification files (requirements, constraints, specs) |
+
+---
+
+### 🏗️ Scale & structure
+
+| Command | What it does |
+|---------|-------------|
+| `/pantion-decompose` | Split large system into architect canon + interface canons + component canons |
+
+---
+
+### ✅ Quality
+
+| Command | What it does |
+|---------|-------------|
+| `/pantion-check` | Check whether canons are complete, consistent, and build-ready |
+
+---
+
+### 🔄 Protocol evolution
+
+| Command | What it does |
+|---------|-------------|
+| `/pantion-update` | Upgrade the protocol itself — ⚠️ may introduce breaking changes |
+| `/pantion-migrate` | Update project to new protocol after an upgrade |
+
+---
+
+### ❓ This command
+
+| Command | What it does |
+|---------|-------------|
+| `/pantion-help` | This overview |
+
+---
+
+**Not sure which command you need?** Just tell me what you want to do, and I'll point you in the right direction."
+
+---
+
+## STEP 3: REDIRECT
+
+If the user asks a question or describes what they want after seeing the overview, redirect:
+
+| The user says... | Redirect to |
+|-----------------|-------------|
+| "I want to build something new" | `/pantion-start` or `/pantion-quick` |
+| "I already have code and want to use Pantion" | `/pantion-onboard` |
+| "I want to understand what my code does" | `/pantion-reverse` |
+| "I was working on something but stopped" | `/pantion-resume` |
+| "I want to change something in an existing canon" | `/pantion-amend` |
+| "I just want to generate the project files" | `/pantion-translate` |
+| "My system is too big" | `/pantion-decompose` |
+| "I want to check if everything is correct" | `/pantion-check` |
+| "I have a better model now" / "My canon is too shallow" | `/pantion-redialog` |
+| "I want to upgrade Pantion itself" | `/pantion-update` |
+| "My project doesn't work anymore after a Pantion update" | `/pantion-migrate` |
+| "What is Pantion?" | Explain briefly (see below) |
+
+---
+
+## IF THE USER ASKS: "WHAT IS PANTION?"
+
+Say:
+
+"Pantion is a protocol that helps you go from idea to working system through a structured conversation.
+
+Instead of writing a spec, you describe what you want to build. I ask the right questions until your intent is clear — no more guesswork. That conversation becomes the source of truth (the 'canon'). Everything that follows — code, configuration, documentation — is derived from that canon.
+
+Core principle: **code is replaceable, intent is rebuildable.**
+
+Want to get started? Type `/pantion-start` for the full protocol, or `/pantion-quick` if you want to prototype quickly."

package/protocol/commands/migrate.md

@@ -0,0 +1,173 @@
+# /pantion-migrate — Update project to new protocol version
+
+After a `pantion_update`, the protocol may have changed. This command updates an existing project
+so that canons and derived files are compatible with the new version.
+
+---
+
+## WHEN YOU ARRIVE HERE
+
+- After a `pantion_update` that contained breaking changes
+- When opening a project created with an older Pantion version
+- When `pantion_check` reports issues indicating protocol mismatch
+
+---
+
+## STEP 1: DETECT VERSION MISMATCH
+
+Check:
+
+1. **Protocol version**: which protocol commands/rules are installed?
+2. **Canon version**: which canons exist, and when were they created?
+3. **Changelog**: is there a `protocol/snapshots/pantion-changelog-[date].md` available?
+
+If there's a changelog, read the breaking changes.
+If there's no changelog, compare the current protocol files with the structure of the canons.
+
+Report:
+
+"This project uses Pantion canons from [date/version].
+The installed Pantion protocol is from [date/version].
+
+**Changes found:**
+- [change 1]: impact on this project: [yes/no]
+- [change 2]: impact on this project: [yes/no]
+
+**Action needed:**
+- [list of what needs to be updated]
+
+Would you like me to perform the migration?"
+
+---
+
+## STEP 2: EVALUATE CANONS
+
+Read all canons in `canon/` and check per canon:
+
+### Structural checks:
+- [ ] Stamp format: does it contain all fields the new version expects?
+- [ ] Canon Type: is it recognized by the new version?
+- [ ] Authority Budget: does it fit the new structure (e.g., Rights/Consumption split)?
+- [ ] Interface Canons: do they contain the fields the new version expects?
+
+### Content checks:
+- [ ] Are there new convergence elements the old version didn't cover?
+- [ ] Are there concepts that have been renamed or restructured?
+
+### Classification per canon:
+
+| Canon | Status | Migration needed |
+|-------|--------|-----------------|
+| [name] | compatible | no |
+| [name] | stamp outdated | update stamp |
+| [name] | missing fields | supplement or OPEN QUESTION |
+| [name] | incompatible | redialog needed |
+
+---
+
+## STEP 3: PERFORM MIGRATION
+
+### Level 1 — Automatic (no content changes)
+
+Safe updates that don't affect intent:
+
+- **Update stamps**: add fields the new version expects, with values derived from the canon
+- **Update index**: adjust `canon/index.md` to new template format
+- **Update traceability**: adjust format
+- **Update comments**: `<!-- Derived from: ... -->` in derived files
+
+Execute this automatically after confirmation.
+
+### Level 2 — Semi-automatic (minor content additions)
+
+Updates that require interpretation but are likely safe:
+
+- **Restructure Authority Budget**: if the new version distinguishes Rights/Consumption, split existing budget items
+- **Supplement interface fields**: if the new version expects additional contract fields, derive from existing canon or mark as OPEN QUESTION
+- **Add new metadata**: e.g., Decompose Score, session count
+
+Present each change to the user: "I want to supplement [X] with [Y], derived from [Z]. Agree?"
+
+### Level 3 — Manual (redialog needed)
+
+If a canon is substantively insufficient for the new version:
+
+"Canon [name] is missing [element] that the new version requires. I cannot supplement this automatically — it requires a new convergence dialog.
+
+Options:
+A) Start a short convergence session to supplement the missing element (via `pantion_resume`)
+B) Mark as OPEN QUESTION and update later
+C) Leave it as-is (the canon remains valid but is not fully compliant with the new standard)"
+
+---
+
+## STEP 4: REGENERATE DERIVED FILES
+
+After updating the canons, regenerate all derived files:
+
+1. Read the updated canons
+2. Run the translation step again (as in `pantion_translate`)
+3. Keep a backup of the old files (for diff/review)
+4. Generate the new files
+5. Update `canon/traceability.md`
+
+### Present diff:
+
+"Here are the changes in the derived files:
+
+**spec/requirements.md:**
+- [what changed]
+
+**spec/constraints.md:**
+- [what changed]
+
+**[etc.]**
+
+Would you like to accept the changes?"
+
+---
+
+## STEP 5: VALIDATION
+
+Automatically run `pantion_check` on all updated canons.
+
+If all pass:
+"Migration successful. All canons are compatible with the new version."
+
+If there are issues:
+"Migration mostly successful, but there are [N] open items:
+[list]
+
+Use `pantion_resume` to answer the open items."
+
+---
+
+## STEP 6: REPORT
+
+"Migration completed for [project name].
+
+**Canons updated:** [N] of [total]
+- Automatic: [N]
+- Semi-automatic: [N]
+- Open for redialog: [N]
+
+**Derived files regenerated:** [N]
+**Validation:** PASS | [N] open items
+
+Backup of old files: [location]"
+
+---
+
+## SPECIAL SITUATIONS
+
+### No changelog available
+If there's no changelog (e.g., the update was done manually), compare the structure:
+- Which stamp fields does the new version expect?
+- Which command structure has changed?
+- Make a best-effort analysis and present it to the user.
+
+### Multiple projects
+"You have multiple projects that use Pantion. `pantion_migrate` works per project. Run it in each project separately."
+
+### Project with DRAFT canons
+DRAFT canons are not migrated — they are still in flux. After migration, use `pantion_resume` to finalize them with the new version.

package/protocol/commands/onboard.md

@@ -0,0 +1,210 @@
+# /pantion-onboard — Add Pantion to an existing project
+
+You have an existing project with code. You want to introduce Pantion.
+This command guides you through the choice of how, and executes it.
+
+---
+
+## STEP 1: EXPLORE THE PROJECT
+
+Scan the project:
+
+- How much code is there? (files, lines, languages)
+- Is there documentation? (README, docs/, comments)
+- Are there tests?
+- Is there already a `.claude/` directory?
+- Are there existing specs, PRDs, tickets, or other intent descriptions?
+
+Report:
+
+"I've explored your project:
+
+**Code:** [N] files, [N] lines, languages: [list]
+**Documentation:** [present/not present, what]
+**Tests:** [present/not present, coverage if estimable]
+**Existing specs:** [present/not present, what]
+
+Based on this, I'll present you with three options."
+
+---
+
+## STEP 2: CHOOSE STRATEGY
+
+Present the three strategies:
+
+"How do you want to use Pantion in this project?
+
+**A) Forward only** — Pantion for all new changes
+- Existing code stays as-is
+- Every new feature, change, or bugfix goes through a canon
+- Lightest approach, immediately productive
+- No traceability to existing code
+
+**B) Full reverse** — First canonize the entire codebase
+- I'll run /pantion-reverse on the complete codebase
+- You get a complete canon of what the system currently does
+- Then you continue working via the canon
+- Heaviest approach, but full traceability
+
+**C) Partial** — Only canonize what you're going to touch
+- You point out which part you're going to change
+- I'll run /pantion-reverse on only that part
+- The rest stays undocumented until you touch it
+- Pragmatic, grows organically
+
+Which fits your situation?"
+
+---
+
+## STEP 3A: FORWARD ONLY
+
+### Installation
+1. Create `canon/` directory
+2. Initialize `canon/index.md`
+3. Create `canon/baseline.md`:
+
+```markdown
+# Baseline
+
+This project existed before Pantion was introduced.
+The code present on [date] has no canon.
+
+Pantion is active for all changes from [date] onward.
+Existing code will be canonized when it is touched (see strategy C: partial).
+
+## Existing project
+- **Languages:** [list]
+- **Size:** [estimate]
+- **Documentation:** [what exists]
+- **Tests:** [what exists]
+```
+
+4. Project specification files (`spec/`) come with the first canon via `/pantion-translate`.
+
+### Wrap up
+
+"Pantion has been installed alongside your existing project.
+
+From now on:
+- New feature: use `pantion_start`
+- Change to canonized code: use `pantion_amend`
+- Touching existing code: use `pantion_onboard` again (strategy C for that part)
+
+The existing codebase has no canon. That's fine — you build up organically."
+
+---
+
+## STEP 3B: FULL REVERSE
+
+### Size estimation
+Scale the approach based on project size:
+
+**Small (< 20 files, < 2000 lines):**
+- Run `/pantion-reverse` directly on the entire codebase
+- One standalone canon
+
+**Medium (20-100 files, 2000-15000 lines):**
+- Run `/pantion-reverse` on the entire codebase
+- Consider hierarchical decomposition if there are clearly distinct parts
+
+**Large (> 100 files, > 15000 lines):**
+- Hierarchical approach is almost certainly needed
+- Start with an Architect Canon (system overview)
+- Decompose into components
+- Reverse per component
+
+### Execution
+1. Run `/pantion-reverse` (see that command for the full process)
+2. Let the user review the generated canon
+3. Resolve OPEN QUESTIONS and AMBIGUITIES with the user
+4. Generate project files via `/pantion-translate`
+
+### Wrap up
+
+"The complete codebase has been canonized.
+
+- Canon (dialog): `canon/dialogspec-dialog.md`
+- Summary (derived): `canon/dialogspec-summary.md`
+- Status: [CONVERGED (REVERSE) | DRAFT with N open questions]
+- Traceability: `canon/traceability.md` (canon -> source code)
+
+From now on, the project works entirely via Pantion.
+Changes via `pantion_amend`, new features via `pantion_start`."
+
+---
+
+## STEP 3C: PARTIAL
+
+### Determine scope
+
+Ask: "Which part of the project are you going to touch? Describe it in your own words, or point me to the files/directories."
+
+Identify the scope:
+- Which files/modules/directories belong to it?
+- Where does this part touch the rest of the project? (interfaces)
+- Is this part independent enough to canonize separately?
+
+### Boundary detection
+
+Analyze the boundaries of the selected part:
+
+"This part touches the rest of the project at these points:
+- [interface 1: description]
+- [interface 2: description]
+
+Would you like to canonize these interfaces as well, or treat them as 'existing environment'?"
+
+**Option 1 — Include interfaces:** Generate Interface Canons for the couplings. This gives sharper contracts but takes more time.
+
+**Option 2 — Treat interfaces as given:** Describe the interfaces as external constraints in the component canon. Faster, but less traceability.
+
+### Execution
+1. Run `/pantion-reverse` on only the selected part
+2. Treat the rest of the project as context (not as code to be canonized)
+3. Generate a component canon with:
+   - `INHERITED CONSTRAINTS: derived from the broader codebase`
+   - `EXTERNAL INTERFACES: [description of how this part touches the rest]`
+4. Resolve OPEN QUESTIONS with the user
+5. Generate project files for this part
+
+### Wrap up
+
+"Part [name] has been canonized.
+
+- Canon (dialog): `canon/components/component-[name]-dialog.md`
+- Summary (derived): `canon/components/component-[name]-summary.md`
+- Status: [CONVERGED (REVERSE) | DRAFT]
+- Interfaces: [canonized | described as constraint]
+
+The rest of the project has no canon. When you touch another part,
+run `pantion_onboard` again for that part — it grows organically."
+
+---
+
+## STEP 4: HYGIENE CHECK
+
+Regardless of the chosen strategy, check at the end:
+
+- [ ] `canon/index.md` has been created and is current
+- [ ] `canon/baseline.md` describes the starting situation
+- [ ] Existing project configuration has not been broken
+- [ ] Existing documentation has been supplemented, not overwritten
+- [ ] The user knows which flow to follow for their next change
+
+---
+
+## SPECIAL SITUATIONS
+
+### There are already specs/PRDs/tickets
+"I see there are already specification documents: [list]. Would you like me to include these as input for the canonization? They then become part of the dialog — not the canon itself."
+
+Use existing specs as context during the reverse process, but the canon remains the verbatim dialog.
+
+### The project already uses another spec method
+"This project uses [method]. Pantion doesn't necessarily replace it — it adds a canonical intent layer. The existing [specs/tickets/PRDs] can serve as input for convergence. Would you like to work side by side, or switch over completely?"
+
+### Multiple developers
+"Are multiple people working on this project? If so, it's important that everyone knows:
+- The canon in `canon/` is the source of truth
+- Changes go through `pantion_amend`
+- The generated files in `spec/` are derived — don't edit them manually"