mdan-cli 2.2.0

package/integrations/all-integrations.md

@@ -0,0 +1,300 @@
+# MDAN Integration — ChatGPT / OpenAI
+
+## Setup
+
+### GPT-4o / GPT-4 (Web)
+
+1. Go to chat.openai.com
+2. Start a new conversation
+3. Paste the content of `core/orchestrator.md` as your first message, prefixed with:
+   ```
+   Please adopt the following role and follow these instructions for our entire conversation:
+   
+   [paste orchestrator.md content here]
+   ```
+
+### Custom GPT
+
+1. Go to GPT Builder
+2. In "Instructions", paste `core/orchestrator.md`
+3. Upload agent files as knowledge files
+4. Name your GPT "MDAN Core"
+
+### API
+
+```python
+from openai import OpenAI
+
+with open("core/orchestrator.md") as f:
+    system_prompt = f.read()
+
+client = OpenAI()
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": "I want to build [your project idea]"}
+    ]
+)
+```
+
+## Notes for ChatGPT
+
+- Replace `[MDAN-AGENT]` XML tags with `## MDAN AGENT` markdown headers if tags cause issues
+- GPT-4o handles the full Universal Envelope well
+- For long projects, use Projects (ChatGPT Plus) to maintain context
+
+---
+
+# MDAN Integration — Google Gemini
+
+## Setup
+
+### Gemini (Web)
+
+Gemini works best with markdown-formatted prompts. Convert the orchestrator to markdown:
+
+```
+# MDAN Core — Orchestrator
+
+You are MDAN Core, the central orchestrator...
+[rest of orchestrator.md, with [MDAN-AGENT] blocks replaced by ## headers]
+```
+
+### Gemini API
+
+```python
+import google.generativeai as genai
+
+with open("core/orchestrator.md") as f:
+    system_prompt = f.read()
+
+genai.configure(api_key="YOUR_API_KEY")
+model = genai.GenerativeModel(
+    model_name="gemini-1.5-pro",
+    system_instruction=system_prompt
+)
+chat = model.start_chat()
+response = chat.send_message("I want to build [your project idea]")
+```
+
+## Notes for Gemini
+
+- Gemini handles markdown well; prefer `## Headers` over XML-style tags
+- Gemini 1.5 Pro has a very large context window — excellent for long MDAN sessions
+- Use Gemini Advanced for best results
+
+---
+
+# MDAN Integration — Alibaba Qwen
+
+## Setup
+
+### Qwen Web (Tongyi)
+
+1. Go to tongyi.aliyun.com
+2. Paste the orchestrator prompt as the first message
+3. Qwen handles structured prompts well
+
+### Qwen API
+
+```python
+from openai import OpenAI  # Qwen uses OpenAI-compatible API
+
+with open("core/orchestrator.md") as f:
+    system_prompt = f.read()
+
+client = OpenAI(
+    api_key="YOUR_DASHSCOPE_KEY",
+    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
+)
+response = client.chat.completions.create(
+    model="qwen-max",
+    messages=[
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": "I want to build [your project idea]"}
+    ]
+)
+```
+
+## Notes for Qwen
+
+- Qwen supports the Universal Envelope as-is
+- Qwen-Max gives best results for complex orchestration
+- Chinese language support is native — useful for Chinese-language projects
+
+---
+
+# MDAN Integration — Moonshot Kimi
+
+## Setup
+
+### Kimi API
+
+```python
+from openai import OpenAI
+
+with open("core/orchestrator.md") as f:
+    system_prompt = f.read()
+
+client = OpenAI(
+    api_key="YOUR_KIMI_KEY",
+    base_url="https://api.moonshot.cn/v1"
+)
+response = client.chat.completions.create(
+    model="moonshot-v1-128k",
+    messages=[
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": "I want to build [your project idea]"}
+    ]
+)
+```
+
+## Notes for Kimi
+
+- Kimi's 128k context window makes it excellent for full project sessions
+- Use markdown headers over XML tags for best compatibility
+- Moonshot-v1-128k is recommended for MDAN due to large context support
+
+---
+
+# MDAN Integration — Zhipu GLM
+
+## Setup
+
+### GLM API
+
+```python
+from zhipuai import ZhipuAI
+
+with open("core/orchestrator.md") as f:
+    system_prompt = f.read()
+
+client = ZhipuAI(api_key="YOUR_API_KEY")
+response = client.chat.completions.create(
+    model="glm-4",
+    messages=[
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": "I want to build [your project idea]"}
+    ]
+)
+```
+
+## Notes for GLM
+
+- GLM-4 handles structured prompts well
+- Use markdown formatting for best results
+- GLM is particularly strong for Chinese-language software projects
+
+---
+
+# MDAN Integration — MiniMax
+
+## Setup
+
+### MiniMax API
+
+```python
+import requests
+
+with open("core/orchestrator.md") as f:
+    system_prompt = f.read()
+
+response = requests.post(
+    "https://api.minimax.chat/v1/text/chatcompletion_v2",
+    headers={"Authorization": "Bearer YOUR_API_KEY"},
+    json={
+        "model": "abab6.5s-chat",
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": "I want to build [your project idea]"}
+        ]
+    }
+)
+```
+
+## Notes for MiniMax
+
+- MiniMax handles the Universal Envelope well
+- Use structured markdown for agent prompts
+
+---
+
+# MDAN Integration — Opencode
+
+## Setup
+
+Opencode is a terminal-based AI coding tool. MDAN integrates via its system prompt configuration.
+
+### Configuration
+
+```bash
+# In your project root, create opencode.json
+cat > opencode.json << 'EOF'
+{
+  "system": "$(cat core/orchestrator.md)"
+}
+EOF
+```
+
+Or set via environment:
+
+```bash
+export OPENCODE_SYSTEM="$(cat core/orchestrator.md)"
+opencode
+```
+
+### Usage
+
+```bash
+# Start MDAN session
+opencode "I want to build [your project idea]"
+
+# Reference agent prompts
+opencode "@file .mdan/agents/dev.md Implement the user authentication feature"
+```
+
+## Notes for Opencode
+
+- Opencode excels in the BUILD phase — it can directly edit files
+- Use MDAN feature briefs as opencode tasks
+- Place agent files in `.mdan/agents/` for easy reference
+
+---
+
+# MDAN Integration — GitHub Copilot
+
+## Setup
+
+GitHub Copilot supports workspace instructions via `.github/copilot-instructions.md`.
+
+### Step 1: Create workspace instructions
+
+```bash
+mkdir -p .github
+cat core/orchestrator.md > .github/copilot-instructions.md
+```
+
+### Step 2: Activate in VS Code
+
+1. Open VS Code with GitHub Copilot extension
+2. Open Copilot Chat (Ctrl+Shift+I)
+3. The workspace instructions are automatically loaded
+
+### Step 3: Use MDAN phases
+
+```
+@workspace MDAN Phase 1: I want to build [your project idea]
+```
+
+## Limitations with GitHub Copilot
+
+- Copilot Chat has a shorter context window than dedicated LLM APIs
+- Orchestration is more limited than with Claude or GPT-4
+- Best used for the BUILD phase with pre-written architecture docs
+- Use `@workspace` to give Copilot context from your codebase
+
+## Recommended Usage
+
+Use Copilot primarily for the BUILD phase — once the architecture and PRD are written 
+(using Claude, GPT-4, or Gemini), Copilot excels at implementing features directly in your IDE.

package/integrations/claude.md

@@ -0,0 +1,46 @@
+# MDAN Integration — Claude (Anthropic)
+
+## Setup
+
+Claude is the reference implementation for MDAN. It handles the Universal Envelope natively.
+
+### Option 1: claude.ai (Web/App)
+
+1. Open a new Claude conversation
+2. Start your message with the content of `core/orchestrator.md`
+3. Optionally add the relevant agent prompts for your current phase
+4. Begin your project
+
+### Option 2: API / Custom Claude App
+
+```python
+import anthropic
+
+with open("core/orchestrator.md") as f:
+    system_prompt = f.read()
+
+client = anthropic.Anthropic()
+
+response = client.messages.create(
+    model="claude-opus-4-20250514",
+    max_tokens=8096,
+    system=system_prompt,
+    messages=[
+        {"role": "user", "content": "I want to build [your project idea]"}
+    ]
+)
+```
+
+### Option 3: Claude Projects
+
+1. Create a new Claude Project
+2. In Project Instructions, paste the content of `core/orchestrator.md`
+3. Upload relevant agent files to Project Knowledge
+4. Start new conversations within the project
+
+## Tips for Claude
+
+- Claude handles XML-style `[MDAN-AGENT]` tags natively — use them as-is
+- For long projects, use Claude Projects to maintain context
+- Claude responds well to "DESIGN APPROVED" / "PRD APPROVED" validation phrases
+- Use extended thinking (if available) for complex architecture decisions

package/integrations/cursor.md

@@ -0,0 +1,74 @@
+# MDAN Integration — Cursor IDE
+
+## Setup
+
+Cursor uses `.cursorrules` for persistent AI instructions at the project level.
+
+### Step 1: Create `.cursorrules`
+
+Copy `core/orchestrator.md` content into a `.cursorrules` file at your project root, then add:
+
+```
+## CURSOR-SPECIFIC INSTRUCTIONS
+
+You are operating inside Cursor IDE. In addition to your MDAN orchestration role:
+
+- You have access to the full codebase via @codebase
+- You can read and write files directly
+- Use @file to reference specific files when activating agents
+- When the Dev Agent produces code, write it directly to the appropriate files
+- When the Doc Agent produces documentation, write it to the mdan_output/ folder
+
+### Agent File References
+- Product Agent: @file .mdan/agents/product.md
+- Architect Agent: @file .mdan/agents/architect.md
+- UX Agent: @file .mdan/agents/ux.md
+- Dev Agent: @file .mdan/agents/dev.md
+- Test Agent: @file .mdan/agents/test.md
+- Security Agent: @file .mdan/agents/security.md
+- DevOps Agent: @file .mdan/agents/devops.md
+- Doc Agent: @file .mdan/agents/doc.md
+```
+
+### Step 2: Copy agents to project
+
+```bash
+mkdir -p .mdan/agents
+cp agents/*.md .mdan/agents/
+```
+
+### Step 3: Start using MDAN in Cursor
+
+Open Cursor Chat (Cmd+L) and type:
+```
+MDAN: I want to build [your project idea]
+```
+
+## Cursor-Specific Features
+
+### Composer Mode (Recommended)
+Use Composer (Cmd+I) for BUILD phase — it can write multiple files simultaneously when the Dev Agent produces code.
+
+### Agent Mode
+Enable Agent mode for autonomous implementation. MDAN Core will orchestrate, and Cursor's agent will execute file operations.
+
+### @references
+- `@codebase` — Give MDAN Core full project context
+- `@file path/to/file` — Reference specific files for agent review
+- `@docs` — Reference documentation
+
+## Example `.cursorrules` file structure
+
+```
+.cursorrules          ← MDAN Core orchestrator prompt
+.mdan/
+  agents/
+    product.md
+    architect.md
+    ux.md
+    dev.md
+    test.md
+    security.md
+    devops.md
+    doc.md
+```

package/integrations/windsurf.md

@@ -0,0 +1,48 @@
+# MDAN Integration — Windsurf IDE
+
+## Setup
+
+Windsurf uses `.windsurfrules` for persistent AI instructions.
+
+### Step 1: Create `.windsurfrules`
+
+```bash
+cp core/orchestrator.md .windsurfrules
+```
+
+Then append at the end:
+
+```
+## WINDSURF-SPECIFIC INSTRUCTIONS
+
+You are operating inside Windsurf IDE with Cascade AI.
+
+- Cascade can autonomously execute multi-step coding tasks
+- Use MDAN phases to structure Cascade's work
+- When activating the Dev Agent, Cascade will implement and write files directly
+- Use Cascade's flow awareness to maintain MDAN phase context across sessions
+
+### File Organization
+All MDAN artifacts should be saved to `.mdan/artifacts/` for reference.
+```
+
+### Step 2: Copy agents
+
+```bash
+mkdir -p .mdan/agents .mdan/artifacts
+cp agents/*.md .mdan/agents/
+```
+
+### Step 3: Using MDAN with Cascade
+
+Cascade's multi-step reasoning pairs well with MDAN's structured phases. When starting a phase:
+
+```
+@MDAN Phase 2: DESIGN — activate Architect Agent for [project name]
+```
+
+## Tips for Windsurf
+
+- Windsurf's Cascade is excellent for the BUILD phase — it can implement entire features autonomously
+- Use MDAN's Feature Briefs as Cascade tasks for predictable, structured implementation
+- Save architecture documents to `.mdan/artifacts/` so Cascade can reference them in context

package/memory/MDAN-STATE.template.json

@@ -0,0 +1,44 @@
+{
+  "mdan_version": "2.0.0",
+  "user": {
+    "name": null
+  },
+  "project": {
+    "name": "{{PROJECT_NAME}}",
+    "type": null,
+    "detected_profile": null,
+    "created_at": "{{DATE}}",
+    "last_updated": "{{DATE}}"
+  },
+  "current_phase": "DISCOVER",
+  "phase_history": [
+    {
+      "phase": "DISCOVER",
+      "started_at": "{{DATE}}",
+      "completed_at": null,
+      "status": "IN_PROGRESS",
+      "artifacts": []
+    }
+  ],
+  "agents_used": {
+    "learn": null,
+    "product": null,
+    "architect": null,
+    "ux": null,
+    "dev": null,
+    "test": null,
+    "security": null,
+    "devops": null,
+    "doc": null
+  },
+  "features": [],
+  "decisions": [],
+  "open_issues": [],
+  "tech_stack": {},
+  "learned_knowledge": {
+    "skills": [],
+    "mcp_servers": [],
+    "rulesets": []
+  },
+  "llm_history": []
+}

package/memory/MEMORY-SYSTEM.md

@@ -0,0 +1,197 @@
+# MDAN Memory System
+
+> La mémoire persistante de MDAN entre les sessions.  
+> Chaque projet génère et maintient un fichier `MDAN-STATE.json` à la racine.
+
+---
+
+## Concept
+
+Le problème fondamental des agents IA : chaque nouvelle conversation repart de zéro.  
+MDAN résout ça avec un fichier d'état JSON versionné, lisible par n'importe quel LLM.
+
+Au début de chaque session, l'utilisateur colle le contenu de `MDAN-STATE.json` dans la conversation.  
+MDAN Core le lit, reconstruit le contexte complet, et reprend exactement où on s'était arrêté.
+
+---
+
+## Structure du fichier MDAN-STATE.json
+
+```json
+{
+  "mdan_version": "2.0.0",
+  "user": {
+    "name": "Alex"
+  },
+  "project": {
+    "name": "mon-projet",
+    "type": "web-app",
+    "created_at": "2025-01-15",
+    "last_updated": "2025-01-20"
+  },
+  "current_phase": "BUILD",
+  "phase_history": [
+    {
+      "phase": "DISCOVER",
+      "started_at": "2025-01-15",
+      "completed_at": "2025-01-15",
+      "status": "VALIDATED",
+      "artifacts": ["mdan_output/PRD.md"]
+    },
+    {
+      "phase": "DESIGN",
+      "started_at": "2025-01-16",
+      "completed_at": "2025-01-17",
+      "status": "VALIDATED",
+      "artifacts": ["mdan_output/ARCHITECTURE.md", "mdan_output/UX-SPEC.md"]
+    },
+    {
+      "phase": "BUILD",
+      "started_at": "2025-01-18",
+      "completed_at": null,
+      "status": "IN_PROGRESS",
+      "artifacts": []
+    }
+  ],
+  "agents_used": {
+    "product": "2.0.0",
+    "architect": "2.0.0",
+    "ux": "2.0.0",
+    "dev": "2.0.0",
+    "test": "2.0.0",
+    "security": "2.0.0",
+    "devops": "2.0.0",
+    "doc": "2.0.0"
+  },
+  "features": [
+    {
+      "id": "US-001",
+      "title": "User authentication",
+      "status": "DONE",
+      "implemented_at": "2025-01-18",
+      "files": ["src/auth/auth.service.ts", "src/auth/auth.controller.ts"],
+      "tests": "PASSING",
+      "security_review": "APPROVED"
+    },
+    {
+      "id": "US-002",
+      "title": "User profile management",
+      "status": "IN_PROGRESS",
+      "implemented_at": null,
+      "files": [],
+      "tests": null,
+      "security_review": null
+    },
+    {
+      "id": "US-003",
+      "title": "Dashboard",
+      "status": "TODO",
+      "implemented_at": null,
+      "files": [],
+      "tests": null,
+      "security_review": null
+    }
+  ],
+  "decisions": [
+    {
+      "id": "ADR-001",
+      "title": "PostgreSQL over MongoDB",
+      "made_at": "2025-01-16",
+      "rationale": "Relational data, ACID needed"
+    }
+  ],
+  "open_issues": [
+    {
+      "id": "ISSUE-001",
+      "type": "BLOCKER",
+      "description": "Rate limiting library choice not finalized",
+      "phase": "BUILD"
+    }
+  ],
+  "tech_stack": {
+    "frontend": "React 18 + TypeScript",
+    "backend": "Node.js 20 + Express",
+    "database": "PostgreSQL 16",
+    "cache": "Redis 7",
+    "hosting": "Railway"
+  },
+  "llm_history": [
+    { "session": 1, "llm": "Claude", "phase": "DISCOVER + DESIGN" },
+    { "session": 2, "llm": "Cursor", "phase": "BUILD (US-001)" }
+  ]
+}
+```
+
+---
+
+## Protocole de reprise de session
+
+### Ce que l'utilisateur fait
+
+```
+1. Ouvrir MDAN-STATE.json du projet
+2. Copier le contenu
+3. Ouvrir son LLM avec le prompt MDAN Core
+4. Coller ce message :
+
+"MDAN RESUME SESSION
+[coller le contenu de MDAN-STATE.json]"
+```
+
+### Ce que MDAN Core fait automatiquement
+
+```
+[MDAN CORE — REPRISE DE SESSION]
+
+✅ Projet chargé : [nom]
+✅ Phase courante : [phase] 
+✅ Progression : [X/Y features complètes]
+✅ Dernière session : [LLM utilisé, date]
+
+Contexte reconstruit :
+- PRD : [résumé en 2 lignes]
+- Architecture : [stack + pattern]
+- Fonctionnalités : [liste avec statuts]
+- Issues ouvertes : [liste]
+
+Prochaine action recommandée :
+→ [Action précise à faire maintenant]
+
+Souhaitez-vous continuer avec [action], ou autre chose ?
+```
+
+---
+
+## Mise à jour de l'état
+
+À la fin de chaque session, MDAN Core génère le MDAN-STATE.json mis à jour :
+
+```
+[MDAN CORE — FIN DE SESSION]
+
+Voici votre MDAN-STATE.json mis à jour.
+Remplacez le fichier existant avec ce contenu :
+
+[JSON complet mis à jour]
+```
+
+---
+
+## CLI — Commandes mémoire
+
+```bash
+# Initialiser l'état d'un projet
+mdan memory init mon-projet
+
+# Afficher l'état actuel
+mdan memory status
+
+# Mettre à jour le statut d'une feature
+mdan memory feature US-001 done
+
+# Générer le prompt de reprise
+mdan memory resume
+
+# Valider une phase
+mdan memory phase-complete DISCOVER
+```