@pantion/mcp-server 0.1.0

package/protocol/commands/check.md

@@ -0,0 +1,255 @@
+# /pantion-check — Quality control on canons
+
+Check whether canons are complete, consistent, and build-ready.
+
+---
+
+## STEP 1: FIND AND CLASSIFY CANONS
+
+Scan the `canon/` directory and classify what's there. Look for dialog files (the canon) and their derived summaries:
+
+- Standalone canon? (subdirectory with `dialog.md` + `summary.md`)
+- Architect Canon + Interface Canons + Component Canons? (subdirectories in canon/)
+- Quick canon? (subdirectory with `dialog.md` containing `STATUS: CONVERGED (QUICK)`)
+- Legacy format? (flat `*-dialog.md` files without folder structure)
+
+Report: "I found: [overview]"
+
+If only legacy-format canons are found (no dialog files): warn the user that the dialog is missing and recommend re-converging or accepting limited traceability.
+
+---
+
+## STEP 2: PER-CANON CHECKLIST
+
+For EACH canon, run through the following checklist:
+
+### Basic requirements
+- [ ] Has a DIALOGSPEC STAMP
+- [ ] STATUS is explicit (DRAFT / CONVERGED / CONVERGED (QUICK) / CONVERGED (REVERSE) / AMENDED / RECONVERGED)
+- [ ] CANON TYPE is filled in
+- [ ] PARENT is filled in (or "none")
+
+### 1. Intent clarity (WAT, not HOE)
+- [ ] Primary goal is unambiguous
+- [ ] Formulated from user perspective
+- [ ] No technology dependency
+- [ ] Goal remains stable despite reformulations
+
+**Fail-signals:**
+- "That depends on the implementation"
+- "We'll see about that later"
+- "You should do it roughly like this"
+
+### 2. Observable success
+- [ ] Success criteria are externally verifiable
+- [ ] "It works" has been translated to concrete effects
+- [ ] Multiple persons would independently reach the same conclusion
+
+**Fail-signals:**
+- Success is internally felt, not externally observable
+- No concrete effects described
+
+### 3. Inputs complete (explicit + implicit)
+- [ ] All required information is named or logically derivable
+- [ ] Implicit inputs discussed (context, identity, time, authorization)
+- [ ] No hidden assumptions about what "will be known"
+- [ ] Uncertainty about inputs is made explicit
+
+**Fail-signal:**
+- "The system will know that."
+
+### 4. Outputs unambiguous
+- [ ] Clear what the system produces
+- [ ] Outputs are visible, audible, readable, or observable
+- [ ] Distinction between: direct output, side effects, confirmations, silent failure
+- [ ] No output is "implicit" without being named
+
+### 5. Failure specified (not happy-path-only)
+- [ ] Clear what happens when the goal is not achievable
+- [ ] System fails gracefully, not silently
+- [ ] User is informed on failure
+- [ ] Distinction between: temporary failure, permanent failure, partial success
+
+**Fail-signal:**
+- An agent may not invent how failure feels.
+
+### 6. Constraints absolute
+- [ ] Boundaries are explicitly stated
+- [ ] Constraints are: not context-dependent, not negotiable, not "unless convenient"
+- [ ] Security, privacy, ethics, and resources are named
+- [ ] No implicit escalation of rights
+
+**Litmus test:** Can an agent hide behind this to add "smart" behavior? If yes: **not ready**.
+
+### 7. Non-goals documented
+- [ ] Clear what the system does NOT do
+- [ ] Tempting extensions are explicitly excluded
+- [ ] "That could also work" is explicitly rejected
+- [ ] Boundaries are sharpened through negation
+
+### 8. Ambiguity consciously handled
+- [ ] Contradictory statements are discussed
+- [ ] Uncertainties are: resolved, or explicitly recorded as OPEN QUESTIONS
+- [ ] No "let the agent decide"
+
+### 9. Authority Budget — Rights (ceiling, not additive)
+- [ ] Allowed actions ✅ | ❌
+- [ ] Forbidden actions ✅ | ❌
+- [ ] Data access ✅ | ❌
+- [ ] Data retention ✅ | ❌
+- [ ] User notification ✅ | ❌
+- [ ] Auditability ✅ | ❌
+
+> If this is missing: **not ready** for an autonomous agent.
+
+### 10. Persistence / restart behavior
+- [ ] Clear what data/state survives a restart
+- [ ] Clear what is ephemeral (lost on crash/restart)
+- [ ] If stateful: recovery behavior specified
+
+**Fail-signal:**
+- "It just keeps running" (no restart scenario considered)
+
+### 11. Authority Budget — Consumption (allocatable, additive)
+- [ ] Rate limits ✅ | ❌ | n/a
+- [ ] Cost limits ✅ | ❌ | n/a
+- [ ] Budget allocation (during decomposition) ✅ | ❌ | n/a
+
+### 12. Inference Policy
+- [ ] Explicitly chosen (strict or conservative)
+- [ ] The 5 inference rules are known and applicable
+- [ ] Multiple plausible interpretations → OPEN QUESTION, not "agent decides"
+
+### 13. Dialog stability (convergence test)
+- [ ] New questions yield no new behavior
+- [ ] Reformulations don't change the intent
+- [ ] The dialog would be read identically today or in 5 years
+- [ ] The intent "no longer moves"
+
+**Stop criterion:** The assistant has nothing meaningful left to ask.
+
+### Agent Readiness Test (final check)
+
+Ask this question:
+
+> "Can a competent coding agent, without further interaction, build a functionally equivalent system?"
+
+- [ ] Yes — without assumptions outside inference policy
+- [ ] Yes — without extra specs
+- [ ] Yes — without interpretive freedom
+- [ ] Yes — with auditable behavior (tests + traceability)
+
+**If any "no": not ready.**
+
+### Scorecard
+
+| Score | Status |
+|-------|--------|
+| 0–5   | Idea phase — not ready |
+| 6–9   | Almost, but dangerous |
+| 10–13 | DialogSpec-worthy |
+
+---
+
+## STEP 3: HIERARCHICAL CHECKS (only during decomposition)
+
+### Architect Canon
+- [ ] Decomposition is clear (each part has a clear area of responsibility)
+- [ ] Shared constraints defined
+- [ ] Authority Budget ceiling defined
+- [ ] Interface descriptions present for every coupling
+
+### Component Canons
+- [ ] Inherited constraints explicitly named
+- [ ] No inherited constraint violated
+- [ ] Authority Budget within ceiling
+- [ ] Interface Canons respected
+
+### Interface Canons (during decomposition)
+- [ ] All 5 core fields present (parties, value, guarantees, expectations, failure behavior)
+- [ ] Data Shape described (enumeratively, in natural language)
+- [ ] Versioning/Compat defined (what breaks compatibility?)
+- [ ] Error Semantics described (which failure categories?)
+- [ ] Privacy/Classification addressed (what is PII, who may see what?)
+- [ ] Rate/Cost Expectations documented (what is normal, what is a peak?)
+
+### System-wide consistency
+- [ ] COVERAGE: all Component Canons together cover the system intent
+- [ ] NO GAPS: every behavior is owned by exactly one component
+- [ ] NO OVERLAP: no behavior appears in multiple components
+- [ ] INTERFACE CONSISTENCY: what A promises = what B expects
+- [ ] CONSTRAINT PROPAGATION: no component violates inherited constraints
+- [ ] **AUTHORITY BUDGET — Rights**: no component exceeds the ceiling from the Architect Canon
+- [ ] **AUTHORITY BUDGET — Consumption**: sum of component allocations fits within system budget
+- [ ] **AUTHORITY BUDGET — Allocation**: if the Architect Canon includes a budget distribution, it is complete and consistent
+- [ ] NON-GOALS: system-wide non-goals do not appear as goals in components
+
+---
+
+## STEP 4: CANON INDEX CHECK
+
+Check if `canon/index.md` exists and is current:
+
+- [ ] `canon/index.md` exists
+- [ ] All found canons are listed
+- [ ] STATUS per canon is correct
+- [ ] Open Questions backlog is current (no resolved questions still listed)
+- [ ] Amendments are logged
+
+---
+
+## STEP 5: FILES CHECK (always-on traceability)
+
+Check if derived files are in sync with the canons:
+
+- [ ] Dialog file (canon) exists for each canon (`canon/{naam}/dialog.md`)
+- [ ] Summary file exists and is marked as derived (`<!-- Derived from: ... -->`)
+- [ ] Summary is not newer than dialog without a regeneration comment
+- [ ] canon/{naam}/spec/requirements.md matches canon intent (if generated)
+- [ ] canon/{naam}/spec/constraints.md matches canon constraints (if generated)
+- [ ] canon/{naam}/spec/success-criteria.md matches canon success criteria (if generated)
+- [ ] canon/{naam}/traceability.md exists and is current
+- [ ] Each derived file contains a `<!-- Derived from: canon/{naam}/dialog.md, ... -->` comment
+- [ ] Traceability has been updated after last amend/decompose/translate (not only at translate)
+- [ ] For hierarchical: component spec files match Component Canons
+- [ ] For hierarchical: interface spec files match Interface Canons
+
+---
+
+## STEP 6: REPORT
+
+Produce a report:
+
+```markdown
+# Pantion Check Report — [date]
+
+## Canons found
+[overview]
+
+## Per-canon result
+### [Canon name]: ✅ PASS | ⚠️ WARNING | ❌ FAIL
+[details per failed item]
+
+## Hierarchical consistency (if applicable)
+✅ PASS | ❌ FAIL
+[details]
+
+## Files sync
+✅ IN SYNC | ⚠️ OUT OF SYNC
+[list of files that need to be regenerated]
+
+## Canon Index
+✅ CURRENT | ⚠️ OUTDATED | ❌ MISSING
+
+## Traceability
+✅ CURRENT | ⚠️ OUTDATED | ❌ MISSING
+
+## Recommendations
+[what needs to happen to get everything to ✅]
+```
+
+### If all ✅:
+"All canons are complete and consistent. The system is ready to be built."
+
+### On problems:
+"There are [N] open items. Would you like to resolve them now? I can reopen the dialog for the items that have not yet converged. If the issues are about convergence depth rather than missing information, consider `/pantion-redialog` to re-evaluate with a better model."

package/protocol/commands/create-skill.md

@@ -0,0 +1,81 @@
+# /pantion-create-skill — Create a new Pantion skill through convergence
+
+You are creating a new Pantion skill. A skill is a domain-specific knowledge module that guides future convergence dialogs. You will extract the user's domain expertise through a convergence dialog, and the resulting canon will be the source of truth for the skill.
+
+---
+
+## WHEN YOU ARRIVE HERE
+
+- The user wants to create a new skill for a domain not covered by existing skills
+- The user has domain expertise they want to codify
+- An existing bundled skill is insufficient for the user's domain
+
+---
+
+## RULES (skill-builder specific)
+
+1. Ask ONE question at a time — wait for the answer before asking the next
+2. The user is the domain expert — extract their knowledge, do not assume it
+3. If the user is unsure, mark it as FLEX with a sensible default
+4. Focus on WHAT the skill should teach, not HOW it will be implemented
+5. Cover anti-patterns just as thoroughly as patterns
+
+---
+
+## STEP 1: DOMAIN EXPLORATION
+
+Using the skill-builder's convergence rules, guide the user through:
+
+1. **Domain identity**: What is this domain? Who are the users? What is out of scope?
+2. **Critical questions**: What must always be asked when converging in this domain?
+3. **Common mistakes**: What do agents get wrong in this domain?
+4. **Domain-specific guidance**: What HARD/FLEX boundaries are specific to this domain?
+5. **Output specification**: What should translation produce?
+6. **Vocabulary**: What domain-specific terms exist?
+7. **Keywords**: What terms should trigger this skill?
+
+---
+
+## STEP 2: CONVERGENCE
+
+Apply the full convergence protocol to the skill dialog. The convergence elements adapted for skills:
+
+- **Intent**: What domain knowledge does this skill capture?
+- **Inputs**: What information does the agent need from the user?
+- **Outputs**: What files does translation produce?
+- **Success criteria**: How to verify the skill works?
+- **Failure behavior**: What happens when the skill guides incorrectly?
+- **Non-goals**: What does this skill explicitly NOT cover?
+
+---
+
+## STEP 3: SAVE SKILL CANON
+
+When converged, save the skill canon using `pantion_save-canon` with the `skill_name` parameter. This writes to `skills/{name}/canon/skill-dialog.md`.
+
+---
+
+## STEP 4: TRANSLATE TO SKILL FILES
+
+Use `pantion_translate` to generate the skill files:
+
+1. `skills/{name}/skill.json` — manifest
+2. `skills/{name}/convergence-rules.md` — domain convergence guidance
+3. `skills/{name}/translate.md` — translation instructions
+4. `skills/{name}/prompts/convergence-intro.md` — opening prompt
+5. `skills/{name}/prompts/translate-intro.md` — translation opening prompt
+
+All files are derived from the skill canon dialog. Each contains a derivation comment.
+
+---
+
+## STEP 5: REPORT
+
+"Your new skill '{name}' has been created. It contains:
+- Domain-specific convergence rules
+- Translation instructions for {domain} outputs
+- Opening prompts for convergence and translation
+
+The skill canon is stored in skills/{name}/canon/ — this is the source of truth. The skill files are derived and can be regenerated.
+
+To use this skill, start a new dialog with domain hint '{name}' or its keywords. To improve this skill later, use `/pantion-reskill`."

package/protocol/commands/decompose.md

@@ -0,0 +1,230 @@
+# /pantion-decompose — Split system into subsystems
+
+You are now in Pantion Decompose mode. The system is too large for a single canon.
+You will split it into subsystems, each with their own canon.
+
+---
+
+## WHEN YOU ARRIVE HERE
+
+- From /pantion-start (decomposition signals detected)
+- Directly invoked by the user
+- After a previous quick session that turned out to be too large
+
+### Across multiple sessions
+
+Decomposition often spans multiple sessions. That is normal. If the session can't be completed in one go:
+- Save all canons with their current STATUS (CONVERGED or DRAFT)
+- Note OPEN QUESTIONS per canon in `canon/index.md`
+- Use `/pantion-resume` to continue later
+
+---
+
+## STEP 1: CONVERGE ARCHITECT CANON
+
+### If a dialog is already in progress:
+Use the existing dialog as a starting point. Summarize what you already know and focus on decomposition now.
+
+### If starting fresh:
+Say:
+
+"Your system is large enough to split up. Let's first get the whole picture clear before we define the parts. Describe the complete system at a high level."
+
+### Convergence rules
+1. Ask ONE question at a time — wait for the answer before asking the next
+2. If something has multiple interpretations → ask, don't guess
+
+### Convergence questions now focus on:
+
+1. **System intent**: What is the overarching goal?
+2. **Decomposition**: What logical parts do you see? (let the user lead)
+3. **Shared constraints**: Which rules apply EVERYWHERE? (security, privacy, cost)
+4. **System-wide Authority Budget - Rights**: What is the maximum power level? (ceiling per component)
+5. **System-wide Authority Budget - Consumption**: What is the total rate/cost budget? How is it distributed across components?
+6. **Interfaces**: How do the parts interact? What does A send to B?
+7. **System-wide non-goals**: What does the whole system explicitly NOT do?
+
+### After convergence:
+
+Produce the Architect Canon stamp:
+
+```
+=== DIALOGSPEC STAMP ===
+STATUS: CONVERGED
+DATE: [today]
+MODEL: [model-id (Display Name), e.g. claude-opus-4-6 (Claude Opus 4.6)]
+CANON TYPE: architect
+PARENT: none
+OPEN QUESTIONS: none
+INFERENCE POLICY: conservative
+AUTHORITY BUDGET RIGHTS: complete (ceiling per component)
+AUTHORITY BUDGET CONSUMPTION: complete | n/a (allocation across components)
+STABILITY ZONES: [system-wide HARD invariants]
+FLEX ZONES: [system-wide FLEX defaults]
+COMPONENTS: [list of identified subsystems]
+INTERFACES: [list of interfaces between subsystems]
+=== /DIALOGSPEC STAMP ===
+```
+
+Save the verbatim dialog as `canon/architect-dialog.md` (THE CANON).
+Generate the derived summary as `canon/architect-summary.md`.
+Update `canon/index.md` with the Architect Canon (type, status, date).
+
+Generate the system-wide spec files:
+- `spec/requirements.md` — from system intent + overview of components
+- `spec/constraints.md` — shared constraints
+- `spec/architecture.md` — system-wide ceiling and component boundaries
+
+---
+
+## STEP 2: CONVERGE INTERFACE CANONS
+
+For each identified interface, conduct a short dialog:
+
+Say:
+
+"Now I'll describe the interfaces. Let's start with the coupling between [Component A] and [Component B]. What does A deliver to B? And what does B expect from A?"
+
+Per interface, converge these core fields:
+- Parties
+- Delivered value (both directions)
+- Guarantees
+- Expectations
+- Failure behavior
+- Interface-specific constraints
+
+Plus these five additional contract fields:
+- **Data Shape**: what is exchanged? Describe enumeratively in natural language (not as a schema, but concretely: "A delivers a list of tasks with a title, status, and owner per task")
+- **Versioning/Compat**: what breaks compatibility? What may change without breaking the other side?
+- **Error Semantics**: what specific errors may B expect from A? How are they signaled? (not just "it fails", but which failure categories)
+- **Privacy/Classification**: which data in this interface is PII, confidential, or classified? Which side may see what?
+- **Rate/Cost Expectations**: what is "normal" usage of this interface? What is a peak? Where are the limits?
+
+Produce a stamp per interface:
+
+```
+=== DIALOGSPEC STAMP ===
+STATUS: CONVERGED
+DATE: [today]
+MODEL: [model-id (Display Name), e.g. claude-opus-4-6 (Claude Opus 4.6)]
+CANON TYPE: interface
+PARENT: architect-canon.md
+PARTIES: [Component A] ↔ [Component B]
+=== /DIALOGSPEC STAMP ===
+```
+
+Save the verbatim dialog as `canon/interfaces/interface-[A]-[B]-dialog.md` (THE CANON).
+Generate the derived summary as `canon/interfaces/interface-[A]-[B]-summary.md`.
+Update `canon/index.md` with the Interface Canon (type, status, parties).
+Generate `spec/interfaces/interface-[A]-[B].md` (including data shape, error semantics, privacy/classification, versioning, rate/cost expectations).
+Update `canon/traceability.md`.
+
+---
+
+## STEP 3: CONVERGE COMPONENT CANONS
+
+For each subsystem, conduct a full convergence dialog.
+
+Begin each component dialog with:
+
+"Now we're going to work out [Component name].
+
+Inherited constraints (non-negotiable):
+- [constraint 1 from Architect Canon]
+- [constraint 2 from Architect Canon]
+
+Authority Budget ceiling:
+- [ceiling from Architect Canon]
+
+Interfaces:
+- With [Component X]: [short description]
+- With [Component Y]: [short description]
+
+Describe what this part of the system should do."
+
+### Rules during component convergence:
+- Inherited constraints are NOT negotiable
+- If the user wants something that violates an inherited constraint: "This conflicts with [constraint] from the Architect Canon. That can only be changed via /pantion-amend on the Architect Canon."
+- Authority Budget of this component may be LESS than the ceiling, never MORE
+- Interface Canons must be respected
+
+Produce a stamp per component:
+
+```
+=== DIALOGSPEC STAMP ===
+STATUS: CONVERGED
+DATE: [today]
+MODEL: [model-id (Display Name), e.g. claude-opus-4-6 (Claude Opus 4.6)]
+CANON TYPE: component
+PARENT: architect-canon.md
+INHERITED CONSTRAINTS: [list]
+INTERFACE CANONS: [list]
+=== /DIALOGSPEC STAMP ===
+```
+
+Save the verbatim dialog as `canon/components/component-[name]-dialog.md` (THE CANON).
+Generate the derived summary as `canon/components/component-[name]-summary.md`.
+Update `canon/index.md` with the Component Canon (type, status, parent).
+
+Generate:
+- `spec/components/[name]/requirements.md`
+- Component-specific spec files if needed
+Update `canon/traceability.md`.
+
+---
+
+## STEP 4: CONSISTENCY CHECK
+
+After ALL canons have converged, automatically run the consistency check:
+
+### Check:
+- [ ] **COVERAGE**: Do all Component Canons together cover the full system intent?
+- [ ] **NO GAPS**: Is every aspect of system behavior owned by exactly one component?
+- [ ] **NO OVERLAP**: Does no behavior appear in multiple components?
+- [ ] **INTERFACE CONSISTENCY**: Does what A promises match what B expects?
+- [ ] **CONSTRAINT PROPAGATION**: Does no component violate an inherited constraint?
+- [ ] **AUTHORITY BUDGET — Rights**: no component exceeds the ceiling
+- [ ] **AUTHORITY BUDGET — Consumption**: sum of allocations fits within system budget
+- [ ] **NON-GOALS**: Do system-wide non-goals not appear as goals in components?
+
+### On problems:
+Report each problem and ask the user how it should be resolved.
+Resolve via amendments to the affected canons.
+
+### On success:
+Save the result as `canon/consistency-report.md`.
+
+Say:
+"All canons have converged and are consistent. The system consists of [N] components with [M] interfaces. Would you like me to build? I can build all components sequentially, or you can have them built separately."
+
+---
+
+## STEP 5: BUILD
+
+### Option A — Sequential (one agent builds everything)
+Build each component in order, respecting the interfaces.
+
+### Option B — Independent (user builds parts separately)
+Produce per component a build instruction the user can give to any agent:
+
+```markdown
+## Build instruction for [Component name]
+
+Read the following files:
+- spec/components/[name]/requirements.md (your primary source)
+- spec/constraints.md (inherited boundaries)
+- spec/interfaces/interface-[name]-[X].md (your interfaces)
+
+Build the component. Respect all constraints and interfaces.
+Produce interface stubs/mocks so other components can test independently.
+```
+
+---
+
+## RECURSION
+
+If a Component Canon itself becomes too large, say:
+
+"Component [name] is complex enough to split up on its own. I'm going to apply /pantion-decompose recursively to this component."
+
+The component then becomes an Architect Canon for a sub-decomposition.