mdan-cli 2.2.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "mdan-cli",
+  "version": "2.2.0",
+  "description": "Multi-Agent Development Agentic Network - A modern, adaptive, LLM-agnostic methodology for building software",
+  "main": "cli/mdan.js",
+  "bin": {
+    "mdan": "cli/mdan.js"
+  },
+  "scripts": {
+    "postinstall": "node cli/postinstall.js"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "llm",
+    "development",
+    "methodology",
+    "cursor",
+    "claude",
+    "windsurf",
+    "copilot"
+  ],
+  "author": "khalilbenaz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/khalilbenaz/MDAN.git"
+  },
+  "homepage": "https://github.com/khalilbenaz/MDAN#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "cli/",
+    "core/",
+    "agents/",
+    "phases/",
+    "templates/",
+    "integrations/",
+    "memory/",
+    "skills/",
+    "install.sh"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.0.1",
+    "picocolors": "^1.1.1"
+  }
+}

package/phases/01-discover.md

@@ -0,0 +1,136 @@
+# MDAN Phase 1 — DISCOVER
+
+> **Goal:** Deeply understand the user's need before touching any solution.  
+> **Agents:** Product Agent  
+> **Output:** Validated PRD
+
+---
+
+## Phase Overview
+
+The DISCOVER phase is the foundation of every MDAN project. A rushed discovery means everything 
+built on top of it will be wrong. MDAN Core enforces a thorough discovery before ANY technical 
+work begins.
+
+**Duration:** As long as it takes to answer every question with confidence.  
+**Shortcut:** Never. Discovery shortcuts are the #1 cause of failed software projects.
+
+---
+
+## MDAN Core Behavior in DISCOVER
+
+When the user presents a project idea, MDAN Core ALWAYS:
+
+1. **Acknowledges** the project idea warmly
+2. **Announces** Phase 1: DISCOVER
+3. **Asks the 5 Discovery Questions** (see below)
+4. **Activates the Product Agent** with the user's answers
+5. **Presents the PRD** to the user for validation
+6. **Runs the Phase Gate check** before proceeding
+
+---
+
+## The 5 Essential Discovery Questions
+
+MDAN Core asks these questions every time, without exception:
+
+```
+🔍 MDAN — Phase 1: DISCOVER
+
+Before we build anything, I need to understand what we're actually solving.
+Please answer these 5 questions as completely as you can:
+
+1. WHAT is the core problem you're solving?
+   (Not the solution — the actual problem users face today)
+
+2. WHO are your users?
+   (Be specific: roles, technical level, context of use)
+
+3. HOW will you know if it's successful?
+   (Concrete metrics: "X users per month", "reduces time from Y to Z", etc.)
+
+4. WHAT are your constraints?
+   (Timeline, budget, team size, existing tech, non-negotiables)
+
+5. WHAT have you already tried?
+   (Existing solutions, past attempts, why they didn't work)
+```
+
+---
+
+## Discovery Depth Guide
+
+| Answer Quality | MDAN Core Response |
+|---|---|
+| Vague ("I want an app") | Ask follow-up until specific |
+| Partial (3/5 questions) | Ask for missing answers |
+| Contradictory | Point out the contradiction, resolve first |
+| Complete and clear | Activate Product Agent |
+
+---
+
+## Product Agent Activation Script
+
+Once discovery answers are complete, MDAN Core activates the Product Agent with this brief:
+
+```
+[ACTIVATING: Product Agent]
+
+Task: Create a complete PRD based on the following discovery information.
+
+Project: [Project Name]
+Problem: [User's answer to Q1]
+Users: [User's answer to Q2]
+Success Metrics: [User's answer to Q3]
+Constraints: [User's answer to Q4]
+Prior Attempts: [User's answer to Q5]
+
+Additional Context: [Any other relevant information from the conversation]
+
+Expected Output: Complete PRD following the MDAN PRD template.
+```
+
+---
+
+## Phase 1 Quality Gate
+
+Before exiting DISCOVER and entering DESIGN, MDAN Core checks:
+
+```
+✅ DISCOVER → DESIGN Quality Gate
+
+[ ] Problem is clearly and specifically defined
+[ ] At least one user persona is fully defined
+[ ] Success metrics are measurable (numbers, not "better" or "faster")
+[ ] Project constraints are documented
+[ ] PRD is complete with MoSCoW prioritization
+[ ] MVP scope is defined and realistic
+[ ] User stories have acceptance criteria
+[ ] Risks are identified with mitigation plans
+[ ] Out of scope items are explicitly listed
+[ ] User has reviewed and validated the PRD
+```
+
+**If any box is unchecked:** MDAN Core does NOT proceed. It identifies the gap and works with the user to fill it.
+
+**If all boxes are checked:** MDAN Core announces Phase 2: DESIGN.
+
+---
+
+## Common Discovery Anti-Patterns
+
+| Anti-Pattern | Why It's Dangerous | MDAN Response |
+|---|---|---|
+| "Just build a Twitter clone" | No clear differentiation or problem | Ask: what specific problem does this solve for which users? |
+| "I want all the features" | Scope creep from day one | Enforce MoSCoW, define MVP |
+| "The tech is already decided" | Solution before problem | Document constraint, still validate need |
+| "Trust me, users need this" | Assumptions not validated | Ask for user research or at least specific examples |
+| "We'll figure out metrics later" | No way to know if it worked | Define metrics now or they'll never be defined |
+
+---
+
+## DISCOVER Phase Artifacts
+
+| Artifact | Template | Owner | Status Needed |
+|---|---|---|---|
+| PRD | `templates/PRD.md` | Product Agent | Validated |

package/phases/02-design.md

@@ -0,0 +1,147 @@
+# MDAN Phase 2 — DESIGN
+
+> **Goal:** Architect the complete solution before writing a single line of code.  
+> **Agents:** Architect Agent, UX Agent  
+> **Output:** Architecture Document + UX Specification
+
+---
+
+## Phase Overview
+
+DESIGN is where the solution takes shape. By the end of this phase, every technical and 
+interface decision should be made. The BUILD phase should have zero architectural surprises.
+
+**Duration:** Until every design question is answered.  
+**Rule:** If you're still making architecture decisions during BUILD, DESIGN failed.
+
+---
+
+## MDAN Core Behavior in DESIGN
+
+1. **Announces** Phase 2: DESIGN
+2. **Reviews** the validated PRD
+3. **Activates Architect Agent** first — system design before interface design
+4. **Reviews** the Architecture Document with the user
+5. **Activates UX Agent** — interface design aligned to architecture
+6. **Reviews** the UX Specification with the user
+7. **Runs Phase Gate check** before proceeding
+
+---
+
+## Architect Agent Activation Script
+
+```
+[ACTIVATING: Architect Agent]
+
+Task: Design the complete system architecture for this project.
+
+PRD: [Paste validated PRD]
+Technical constraints: [From discovery]
+Team profile: [Size, skill level]
+Deployment preferences: [Cloud provider, on-prem, etc.]
+
+Expected outputs:
+1. Architecture diagram (Mermaid)
+2. Technology stack with justifications
+3. Data models
+4. API design
+5. Security architecture
+6. Non-functional requirements strategy
+7. Project structure
+8. Coding conventions
+9. Architecture Decision Records
+```
+
+---
+
+## UX Agent Activation Script
+
+```
+[ACTIVATING: UX Agent]
+
+Task: Design the complete user interface specification for this project.
+
+PRD: [Paste validated PRD — personas and user stories]
+Architecture constraints: [Tech stack, limitations]
+Existing brand/design system: [If any, else "None — create from scratch"]
+
+Expected outputs:
+1. Design system (colors, typography, spacing)
+2. Navigation structure
+3. User flows for all key user stories
+4. Screen specifications with all states
+5. Component specifications
+6. Accessibility requirements
+7. UI copy guidelines
+```
+
+---
+
+## Design Review Process
+
+After each agent delivers its output, MDAN Core:
+
+1. **Checks completeness** against the quality gate
+2. **Cross-checks consistency** — does the UX spec align with the architecture?
+3. **Presents to user** with key decisions highlighted
+4. **Asks for explicit validation** before continuing
+
+```
+📐 Design Review: [Document Name]
+
+Key decisions made in this document:
+1. [Decision]: [Choice made] — Rationale: [Why]
+2. [Decision]: [Choice made] — Rationale: [Why]
+3. [Decision]: [Choice made] — Rationale: [Why]
+
+Please review and confirm:
+[ ] I agree with the technology choices
+[ ] I agree with the data model design
+[ ] I agree with the API design
+[ ] I have no unresolved concerns
+
+Type "DESIGN APPROVED" to proceed to Phase 3: BUILD
+Or describe your concerns and we'll revise.
+```
+
+---
+
+## Phase 2 Quality Gate
+
+```
+✅ DESIGN → BUILD Quality Gate
+
+Architecture:
+[ ] System architecture diagram is complete
+[ ] All PRD requirements are addressed in the architecture
+[ ] Technology stack is fully specified with justifications
+[ ] All data entities and relationships are defined
+[ ] All API endpoints are specified
+[ ] Security architecture is defined (auth, authz, encryption)
+[ ] Non-functional requirements are addressed
+[ ] Project structure is defined
+[ ] Coding conventions are documented
+[ ] At least one ADR is written
+
+UX:
+[ ] Design system is complete (colors, typography, spacing, breakpoints)
+[ ] Navigation structure covers all app sections
+[ ] User flows cover all user stories from PRD
+[ ] Every screen has all states (default, loading, empty, error)
+[ ] Accessibility requirements are defined
+[ ] Mobile behavior is specified
+
+Cross-check:
+[ ] UX spec is consistent with architecture (no impossible requirements)
+[ ] Performance requirements are reflected in both arch and UX
+[ ] Both documents are validated by the user
+```
+
+---
+
+## DESIGN Phase Artifacts
+
+| Artifact | Template | Owner | Status Needed |
+|---|---|---|---|
+| Architecture Document | `templates/ARCHITECTURE.md` | Architect Agent | Validated |
+| UX Specification | *(in-line document)* | UX Agent | Validated |

package/phases/03-build.md

@@ -0,0 +1,113 @@
+# MDAN Phase 3 — BUILD
+
+> **Goal:** Implement the solution with precision, security, and quality.  
+> **Agents:** Dev Agent, Security Agent (concurrent)  
+> **Output:** Working, tested, reviewed code
+
+---
+
+## Phase Overview
+
+BUILD is where the code is written. But in MDAN, BUILD is not "just coding" — it's a structured 
+process where every feature is implemented against a spec, reviewed, and security-checked before 
+moving on.
+
+**Rule:** No feature is "done" until it has tests and passes a security check.
+
+---
+
+## BUILD Workflow (per feature)
+
+```
+For each feature in the PRD (MVP scope):
+
+1. MDAN Core prepares a Feature Brief
+2. Dev Agent implements the feature
+3. Security Agent reviews the implementation
+4. MDAN Core reviews the combined output
+5. User validates (or flags issues)
+6. Move to next feature
+```
+
+---
+
+## Feature Brief Template
+
+MDAN Core creates this before activating the Dev Agent:
+
+```
+[ACTIVATING: Dev Agent]
+
+Feature: [US-XXX: User story title]
+Acceptance Criteria:
+  - Given [context], When [action], Then [outcome]
+  - [Additional criteria]
+
+Architecture context:
+  - Tech stack: [Stack]
+  - Relevant data models: [Models]
+  - Relevant API endpoints: [Endpoints]
+  - Coding conventions: [Link/summary]
+
+UX context:
+  - Relevant screens: [Screen names]
+  - Relevant components: [Component names]
+
+Definition of Done:
+  - [ ] All acceptance criteria met
+  - [ ] Unit tests written and passing
+  - [ ] No critical security issues
+  - [ ] Code follows project conventions
+```
+
+---
+
+## Concurrent Security Review
+
+After Dev Agent delivers code, Security Agent reviews immediately:
+
+```
+[ACTIVATING: Security Agent]
+
+Task: Security review of the following implementation.
+Feature: [Feature name]
+Code: [Dev Agent output]
+
+Focus areas:
+- Input validation
+- Authentication/authorization
+- Data exposure
+- Error handling (no sensitive data in errors)
+- Dependency risks
+```
+
+---
+
+## Phase 3 Quality Gate
+
+```
+✅ BUILD → VERIFY Quality Gate
+
+For each feature:
+[ ] All acceptance criteria are implemented
+[ ] Unit tests exist and pass
+[ ] No CRITICAL or HIGH security findings unresolved
+[ ] Code follows project conventions
+[ ] Error handling is complete
+[ ] No hardcoded secrets
+
+Overall:
+[ ] All MVP features are implemented
+[ ] Code is in version control
+[ ] Environment is reproducible (setup script or Docker)
+```
+
+---
+
+## BUILD Phase Artifacts
+
+| Artifact | Owner | Status Needed |
+|---|---|---|
+| Feature implementations | Dev Agent | Reviewed |
+| Unit tests | Dev Agent | Passing |
+| Security findings (per feature) | Security Agent | Resolved or accepted |

package/phases/04-verify.md

@@ -0,0 +1,101 @@
+# MDAN Phase 4 — VERIFY
+
+> **Goal:** Validate that what was built works correctly, securely, and completely.  
+> **Agents:** Test Agent, Security Agent  
+> **Output:** Validated test suite, security report, signed-off quality gate
+
+---
+
+## Phase Overview
+
+VERIFY is where MDAN proves the software works — not assumes it does. Every acceptance criterion 
+is tested. Every security finding from BUILD is verified as resolved. Performance is measured.
+
+**Rule:** "It works on my machine" is not verification. Repeatable, automated tests are.
+
+---
+
+## MDAN Core Behavior in VERIFY
+
+1. **Announces** Phase 4: VERIFY
+2. **Activates Test Agent** for full test suite creation
+3. **Activates Security Agent** for final security review
+4. **Validates all findings** are resolved or explicitly accepted
+5. **Runs Phase Gate check**
+
+---
+
+## Test Agent Activation Script
+
+```
+[ACTIVATING: Test Agent]
+
+Task: Create and execute the full test suite for this project.
+
+PRD (acceptance criteria): [Link/paste]
+Architecture: [Link/paste]
+Implemented features: [List of completed features]
+
+Expected output:
+1. Complete test plan
+2. Unit tests for all features
+3. Integration tests for critical flows
+4. E2E test scenarios
+5. Performance test criteria
+6. Test results summary
+```
+
+---
+
+## Final Security Review Activation
+
+```
+[ACTIVATING: Security Agent]
+
+Task: Final security review of the complete application.
+
+Previous security findings: [List with resolution status]
+Full codebase: [Context/summary]
+Deployment configuration: [From DevOps Agent if available]
+
+Expected output:
+1. Verification that previous findings are resolved
+2. Any new findings discovered
+3. Final security sign-off (or list of blockers)
+```
+
+---
+
+## Phase 4 Quality Gate
+
+```
+✅ VERIFY → SHIP Quality Gate
+
+Testing:
+[ ] All acceptance criteria have corresponding tests
+[ ] All tests pass (0 failures)
+[ ] Test coverage meets target (e.g., 80%)
+[ ] Integration tests pass
+[ ] At least 3 E2E scenarios pass
+[ ] Performance criteria are met
+
+Security:
+[ ] All CRITICAL findings resolved
+[ ] All HIGH findings resolved or explicitly accepted with rationale
+[ ] Final security review completed
+[ ] No new CRITICAL findings
+
+Quality:
+[ ] No known bugs that affect MVP functionality
+[ ] Error messages are user-friendly (no stack traces exposed)
+[ ] Application handles edge cases gracefully
+```
+
+---
+
+## VERIFY Phase Artifacts
+
+| Artifact | Template | Owner | Status Needed |
+|---|---|---|---|
+| Test Plan | `templates/TEST-PLAN.md` | Test Agent | Complete |
+| Security Report | `templates/SECURITY-REVIEW.md` | Security Agent | Signed off |

package/phases/05-ship.md

@@ -0,0 +1,156 @@
+# MDAN Phase 5 — SHIP
+
+> **Goal:** Deploy with confidence. Document completely. Celebrate responsibly.  
+> **Agents:** DevOps Agent, Doc Agent  
+> **Output:** Live deployment, complete documentation, changelog
+
+---
+
+## Phase Overview
+
+SHIP is the final phase. But shipping is not just "deploying" — it's making sure the product 
+is live, stable, observable, and documented. A product that ships without documentation or 
+monitoring isn't done.
+
+**Rule:** You haven't shipped until users can use it AND you can maintain it.
+
+---
+
+## MDAN Core Behavior in SHIP
+
+1. **Announces** Phase 5: SHIP
+2. **Activates DevOps Agent** for deployment pipeline
+3. **Activates Doc Agent** for complete documentation
+4. **Conducts pre-deployment checklist**
+5. **Validates deployment**
+6. **Celebrates the launch** 🚀
+
+---
+
+## DevOps Agent Activation Script
+
+```
+[ACTIVATING: DevOps Agent]
+
+Task: Prepare and execute deployment for this project.
+
+Architecture: [Link/paste]
+Tech stack: [Stack details]
+Deployment target: [Cloud/infrastructure]
+Environments needed: [dev/staging/prod]
+
+Expected output:
+1. Dockerfile(s)
+2. CI/CD pipeline configuration
+3. Infrastructure as Code
+4. Monitoring and alerting setup
+5. Health check configuration
+6. Deployment runbook
+```
+
+---
+
+## Doc Agent Activation Script
+
+```
+[ACTIVATING: Doc Agent]
+
+Task: Create complete documentation for this project.
+
+PRD: [Link/paste]
+Architecture: [Link/paste]
+API spec: [Link/paste]
+Implemented features: [List]
+
+Expected output:
+1. README.md (installation, configuration, quick start)
+2. API documentation
+3. CHANGELOG.md (initial release)
+4. CONTRIBUTING.md
+5. Any user guides needed
+```
+
+---
+
+## Pre-Deployment Checklist
+
+MDAN Core runs this before any production deployment:
+
+```
+🚀 Pre-Deployment Checklist
+
+Infrastructure:
+[ ] Staging deployment successful and validated
+[ ] Database migrations tested on staging
+[ ] Environment variables configured in production
+[ ] SSL/TLS certificates configured
+[ ] Domain DNS configured
+
+Quality:
+[ ] All VERIFY phase gates passed
+[ ] No open CRITICAL or HIGH issues
+[ ] Load test passed on staging
+
+Operations:
+[ ] Monitoring dashboards configured
+[ ] Alerting configured and tested
+[ ] Rollback procedure documented and tested
+[ ] On-call engineer identified
+[ ] Status page ready (if applicable)
+
+Documentation:
+[ ] README is complete and accurate
+[ ] API documentation is published
+[ ] CHANGELOG reflects current release
+[ ] Runbook is complete
+
+Sign-off:
+[ ] User approves production deployment
+```
+
+---
+
+## Post-Deployment Validation
+
+After deployment, MDAN Core checks:
+
+```
+✅ Post-Deployment Validation
+
+[ ] Application is accessible at production URL
+[ ] Health check endpoint returns 200
+[ ] Key user flows work end-to-end in production
+[ ] No spike in error rates
+[ ] No unexpected latency
+[ ] Monitoring shows healthy metrics
+
+If all pass: SHIP phase complete. Project delivered. 🎉
+If any fail: Immediate rollback + investigate
+```
+
+---
+
+## SHIP Phase Artifacts
+
+| Artifact | Template | Owner | Status Needed |
+|---|---|---|---|
+| Dockerfile(s) | — | DevOps Agent | Complete |
+| CI/CD Pipeline | — | DevOps Agent | Active |
+| Infrastructure code | — | DevOps Agent | Applied |
+| README | `templates/` | Doc Agent | Published |
+| API Docs | — | Doc Agent | Published |
+| CHANGELOG | `templates/CHANGELOG.md` | Doc Agent | Published |
+| Runbook | — | DevOps Agent | Complete |
+
+---
+
+## After SHIP: What's Next?
+
+MDAN ends with SHIP — but software doesn't end there. After a successful ship:
+
+1. **Monitor** the first 48 hours closely
+2. **Gather feedback** from real users
+3. **Prioritize** next sprint from "Should Have" backlog
+4. **Start a new MDAN cycle** for the next iteration
+
+MDAN is designed for iterative development. Each cycle strengthens the product.