@iservu-inc/adf-cli 0.2.0 → 0.3.6

package/.project/docs/PROJECT-STRUCTURE-EXPLANATION.md

@@ -0,0 +1,500 @@
+# ADF Project Structure - Complete Explanation
+
+**Date:** 2025-10-03
+**Purpose:** Clarify the relationship between AgentDevFramework and adf-cli
+
+---
+
+## 🎯 Executive Summary
+
+You have **TWO RELATED BUT SEPARATE PROJECTS** in `D:\Documents\GitHub\`:
+
+1. **AgentDevFramework** - Original framework repository (documentation, templates, scripts)
+2. **adf-cli** - Standalone npm CLI tool (what we've been building for v0.1.0 → v0.3.0)
+
+They serve **different purposes** but share the **same underlying methodology**.
+
+---
+
+## 📁 Project Structure
+
+```
+D:\Documents\GitHub\
+│
+├── AgentDevFramework/           ← FRAMEWORK REPOSITORY
+│   ├── references/              ← Git submodules (4 frameworks)
+│   │   ├── bmad-method/        ← Submodule: https://github.com/bmad-code-org/BMAD-METHOD
+│   │   ├── context-engineering/ ← Submodule: https://github.com/coleam00/context-engineering-intro
+│   │   ├── prps-agentic/       ← Submodule: https://github.com/Wirasm/PRPs-agentic-eng
+│   │   └── spec-kit/           ← Submodule: https://github.com/github/spec-kit
+│   ├── shared/                  ← Agent definitions, templates, workflows
+│   ├── scripts/                 ← Initialization and deployment scripts
+│   ├── docs/                    ← Framework documentation
+│   ├── tools/                   ← IDE-specific configurations
+│   └── [Documentation files]    ← Research, analysis, executive summaries
+│
+└── adf-cli/                     ← STANDALONE CLI TOOL (npm package)
+    ├── lib/                     ← Core CLI implementation
+    │   ├── commands/            ← init, deploy, update commands
+    │   ├── frameworks/          ← Interviewer, quality analyzer, progress tracker
+    │   ├── generators/          ← Tool config generators (NEW in v0.3.0)
+    │   ├── templates/           ← PRP/Balanced/BMAD templates
+    │   └── utils/               ← Helper utilities
+    ├── bin/                     ← CLI entry point (adf command)
+    ├── tests/                   ← 57 unit tests
+    ├── .project/                ← Project documentation & chat history
+    │   ├── chats/
+    │   │   ├── complete/        ← Archived sessions
+    │   │   └── current/         ← Active session status
+    │   └── docs/                ← Architecture, vision, research
+    └── package.json             ← npm package (@iservu-inc/adf-cli@0.3.0)
+```
+
+---
+
+## 🔍 Detailed Comparison
+
+### AgentDevFramework (Original Repository)
+
+**What It Is:**
+- Research and documentation repository
+- Synthesis of 4 frameworks (BMAD, Spec-Kit, Context Engineering, PRPs)
+- Collection of templates, agents, and workflows
+- Git submodules pointing to original framework repos
+
+**What It Contains:**
+```
+AgentDevFramework/
+├── .gitmodules                  # Links to 4 framework repos
+├── references/
+│   ├── bmad-method/            # Git submodule
+│   ├── context-engineering/    # Git submodule
+│   ├── prps-agentic/          # Git submodule
+│   └── spec-kit/              # Git submodule
+├── shared/
+│   ├── agents/                # Agent definitions (analyst, pm, dev, etc.)
+│   ├── templates/             # PRP, PRD, Spec templates
+│   ├── workflows/             # Story PRP, Planning PRP
+│   └── memory/                # Constitution, preferences
+├── scripts/
+│   ├── init.js                # Interactive initialization
+│   ├── deploy.js              # Tool deployment
+│   └── analyze-docs.js        # Documentation analysis
+├── tools/                     # IDE-specific configs
+│   ├── windsurf/
+│   ├── cursor/
+│   └── vscode/
+└── [Documentation]
+    ├── FRAMEWORK-ANALYSIS.md
+    ├── FRAMEWORK-OVERLAP.md
+    ├── EXECUTIVE-SUMMARY.md
+    └── QUICK-START.md
+```
+
+**Purpose:**
+- Research and analysis of frameworks
+- Documentation of unified methodology
+- Templates and agent definitions
+- Reference implementation
+
+**How to Use:**
+```bash
+cd AgentDevFramework
+npm install
+npm run init           # Interactive setup
+npm run deploy -- --tool windsurf
+```
+
+**Status:**
+- ✅ Complete research and documentation
+- ✅ Working scripts
+- ❌ Not an npm package
+- ❌ Requires manual git clone
+- ❌ Node.js scripts, not CLI tool
+
+---
+
+### adf-cli (Standalone CLI Tool)
+
+**What It Is:**
+- **Standalone npm package** you can install globally
+- **Production-ready CLI tool** implementing AgentDevFramework methodology
+- **Independently developed** and maintained
+- **Published to npm** as `@iservu-inc/adf-cli`
+
+**What It Contains:**
+```
+adf-cli/
+├── bin/
+│   └── adf.js                  # CLI entry point
+├── lib/
+│   ├── commands/
+│   │   ├── init.js            # AI-driven interview system
+│   │   ├── deploy.js          # Deploy + generate configs
+│   │   └── update.js          # Version management
+│   ├── frameworks/
+│   │   ├── interviewer.js     # Conversational interview engine
+│   │   ├── progress-tracker.js # Quality-based progress (v0.2.0)
+│   │   ├── answer-quality-analyzer.js # 0-100 scoring
+│   │   ├── session-manager.js  # Resume capability
+│   │   ├── questions.js        # Question database (PRP/Balanced/BMAD)
+│   │   └── output-generators.js # Generate framework docs
+│   ├── generators/             # NEW in v0.3.0
+│   │   ├── tool-config-generator.js    # Base class
+│   │   ├── agents-md-generator.js      # Universal AGENTS.md
+│   │   ├── windsurf-generator.js       # Windsurf configs
+│   │   ├── cursor-generator.js         # Cursor configs
+│   │   ├── vscode-generator.js         # VS Code configs
+│   │   └── index.js
+│   ├── templates/
+│   │   ├── shared/
+│   │   │   ├── agents/        # Agent MD files
+│   │   │   ├── templates/     # PRP, Spec, PRD templates
+│   │   │   └── memory/        # Constitution
+│   │   └── .env.template
+│   └── utils/
+│       ├── project-detector.js
+│       └── copy-templates.js
+├── tests/                      # 57 unit tests
+│   ├── agents-md-generator.test.js
+│   ├── windsurf-generator.test.js
+│   ├── cursor-generator.test.js
+│   ├── vscode-generator.test.js
+│   ├── progress-tracker.test.js
+│   ├── answer-quality-analyzer.test.js
+│   └── session-manager.test.js
+├── .project/
+│   ├── chats/
+│   │   ├── complete/          # Archived chat sessions
+│   │   └── current/           # Active session status
+│   └── docs/
+│       ├── goals/PROJECT-VISION.md
+│       ├── architecture/SYSTEM-DESIGN.md
+│       ├── frameworks/FRAMEWORK-METHODOLOGIES.md
+│       └── tool-integrations/
+│           ├── RESEARCH-FINDINGS.md
+│           └── IDE-CUSTOMIZATIONS.md
+├── package.json               # npm package definition
+├── CHANGELOG.md               # Version history
+└── README.md                  # User documentation
+```
+
+**Purpose:**
+- Production CLI tool
+- Global npm installation
+- AI-driven interview system
+- Quality-based progress tracking
+- Resume capability
+- Tool configuration generation
+- Framework output generation
+
+**How to Use:**
+```bash
+# Install globally
+npm install -g @iservu-inc/adf-cli
+
+# Use anywhere
+cd my-project
+adf init                        # Interactive interview
+adf deploy windsurf             # Generate configs
+adf update                      # Check for updates
+```
+
+**Status:**
+- ✅ Published to npm (v0.3.0 live)
+- ✅ Globally installable
+- ✅ 57 unit tests (78% coverage)
+- ✅ Production-ready
+- ✅ Triple-redundant saves
+- ✅ Resume capability
+- ✅ Tool config generators
+
+---
+
+## 🔄 Relationship Between Projects
+
+### How They Relate
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AgentDevFramework                         │
+│                  (Research Repository)                       │
+│                                                              │
+│  ┌────────────────────────────────────────────────┐         │
+│  │  4 Framework Git Submodules (Research)         │         │
+│  │  • BMAD-METHOD                                 │         │
+│  │  • Spec-Kit                                    │         │
+│  │  • Context Engineering                         │         │
+│  │  • PRPs Agentic Engineering                   │         │
+│  └────────────────────────────────────────────────┘         │
+│                         │                                    │
+│                         │ Synthesized into                   │
+│                         ↓                                    │
+│  ┌────────────────────────────────────────────────┐         │
+│  │  Unified Methodology Documentation             │         │
+│  │  • FRAMEWORK-ANALYSIS.md                       │         │
+│  │  • FRAMEWORK-OVERLAP.md                        │         │
+│  │  • Templates & Agents                          │         │
+│  └────────────────────────────────────────────────┘         │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            │ Inspired & Informed
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│                        adf-cli                               │
+│                   (Production CLI Tool)                      │
+│                                                              │
+│  ┌────────────────────────────────────────────────┐         │
+│  │  Standalone Implementation                      │         │
+│  │  • AI-driven interview system                  │         │
+│  │  • Quality-based progress tracking             │         │
+│  │  • Resume capability                           │         │
+│  │  • Framework output generators                 │         │
+│  │  • Tool config generators                      │         │
+│  └────────────────────────────────────────────────┘         │
+│                         │                                    │
+│                         ↓                                    │
+│  ┌────────────────────────────────────────────────┐         │
+│  │  Published npm Package                         │         │
+│  │  @iservu-inc/adf-cli@0.3.0                    │         │
+│  │  • Globally installable                        │         │
+│  │  • Works anywhere                              │         │
+│  │  • No dependencies on AgentDevFramework repo  │         │
+│  └────────────────────────────────────────────────┘         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Differences
+
+| Aspect | AgentDevFramework | adf-cli |
+|--------|------------------|---------|
+| **Type** | Research repository | Production npm package |
+| **Purpose** | Framework synthesis & documentation | Production CLI tool |
+| **Installation** | `git clone` + `npm install` | `npm install -g @iservu-inc/adf-cli` |
+| **Usage** | `npm run init` (local scripts) | `adf init` (global command) |
+| **Dependencies** | Requires git submodules | Standalone, no submodules |
+| **Distribution** | Git repository only | Published to npm registry |
+| **Target Users** | Framework researchers | End users building projects |
+| **Maintenance** | Research/documentation | Production releases with versions |
+| **Testing** | Manual testing | 57 automated unit tests |
+| **Features** | Basic scripts | Advanced features (resume, quality scoring) |
+
+---
+
+## 🎯 What We've Been Working On
+
+### Our Focus: adf-cli (The Production Tool)
+
+**All our work (v0.1.0 → v0.3.0) has been in:**
+```
+D:\Documents\GitHub\adf-cli\
+```
+
+**NOT in:**
+```
+D:\Documents\GitHub\AgentDevFramework\
+```
+
+### Development Timeline
+
+**v0.1.0 (Initial Release):**
+- ✅ Built standalone CLI tool
+- ✅ Implemented 3 frameworks (PRP, Balanced, BMAD)
+- ✅ Created interview system
+- ✅ Published to npm
+
+**v0.2.0 (Quality & Resume):**
+- ✅ Added quality-based progress tracking
+- ✅ Implemented triple-redundant saves
+- ✅ Built resume capability
+- ✅ Created answer quality analyzer
+- ✅ 33 unit tests
+
+**v0.3.0 (Tool Generators):**
+- ✅ Built AGENTS.md generator
+- ✅ Built Windsurf generator
+- ✅ Built Cursor generator
+- ✅ Built VS Code generator
+- ✅ Enhanced deploy command
+- ✅ 57 unit tests (24 new)
+
+---
+
+## 📊 Current Status
+
+### AgentDevFramework
+```bash
+Location: D:\Documents\GitHub\AgentDevFramework\
+Status:   Research repository (unchanged during our work)
+Purpose:  Framework synthesis and documentation
+Usage:    Reference for methodology
+```
+
+### adf-cli
+```bash
+Location: D:\Documents\GitHub\adf-cli\
+Status:   v0.3.0 published to npm ✅
+Purpose:  Production CLI tool
+Usage:    Global command: adf init, adf deploy, etc.
+npm:      https://www.npmjs.com/package/@iservu-inc/adf-cli
+```
+
+---
+
+## 🚀 How They Work Together
+
+### Conceptual Flow
+
+```
+1. User installs: npm install -g @iservu-inc/adf-cli
+                         ↓
+2. User runs: adf init --balanced
+                         ↓
+3. adf-cli conducts AI-driven interview
+   (Using methodology from AgentDevFramework research)
+                         ↓
+4. adf-cli generates framework outputs
+   (PRP.md, specification.md, plan.md, tasks.md)
+                         ↓
+5. User runs: adf deploy windsurf
+                         ↓
+6. adf-cli generates tool configs
+   (AGENTS.md, .windsurfrules, .windsurf/rules/, etc.)
+                         ↓
+7. User develops in Windsurf with AI agents
+   (Agents reference framework outputs)
+```
+
+### They Are Independent
+
+**AgentDevFramework** could be:
+- Deleted entirely
+- Never cloned
+- Not installed
+
+**adf-cli would still work perfectly** because:
+- ✅ All methodology is embedded in the CLI
+- ✅ All templates are bundled in npm package
+- ✅ All agent definitions are included
+- ✅ No runtime dependency on AgentDevFramework repo
+
+---
+
+## 💡 Clarifying Misconceptions
+
+### ❌ INCORRECT Understanding:
+> "AgentDevFramework is the main framework, and adf-cli is just a deployment tool for it"
+
+### ✅ CORRECT Understanding:
+> "AgentDevFramework is research that inspired adf-cli. adf-cli is a standalone production CLI tool that implements the same methodology but is completely independent."
+
+### ❌ INCORRECT Understanding:
+> "The 4 framework repos are actively used by adf-cli at runtime"
+
+### ✅ CORRECT Understanding:
+> "The 4 framework repos were studied, their best practices were synthesized into adf-cli's question database and templates. adf-cli does not depend on them."
+
+### ❌ INCORRECT Understanding:
+> "I need both folders to use adf-cli"
+
+### ✅ CORRECT Understanding:
+> "adf-cli is a standalone npm package. You only need AgentDevFramework if you're researching the frameworks themselves or want to see the original synthesis work."
+
+---
+
+## 🎓 Analogy
+
+Think of it like this:
+
+**AgentDevFramework** = Research paper + lab notes
+- Contains the research
+- Links to original sources (git submodules)
+- Documents the synthesis process
+- Includes experimental scripts
+
+**adf-cli** = Production pharmaceutical drug
+- Based on the research
+- Independently tested (57 unit tests)
+- Packaged for distribution (npm)
+- Ready for end users
+- No dependency on the research lab
+
+---
+
+## 📁 Summary Table
+
+| Project | Type | Location | Published | Purpose | We Built This? |
+|---------|------|----------|-----------|---------|----------------|
+| **AgentDevFramework** | Research repo | `D:\Documents\GitHub\AgentDevFramework\` | No | Framework synthesis & research | ❌ No (existed before) |
+| **adf-cli** | npm CLI tool | `D:\Documents\GitHub\adf-cli\` | ✅ Yes (npm) | Production CLI for developers | ✅ Yes (v0.1.0 → v0.3.0) |
+
+---
+
+## 🔧 What You Should Use
+
+**For Development Work:**
+```bash
+npm install -g @iservu-inc/adf-cli
+cd your-project
+adf init
+adf deploy windsurf
+```
+
+**For Framework Research:**
+```bash
+cd D:\Documents\GitHub\AgentDevFramework
+npm install
+npm run init
+```
+
+**Recommendation:** Use **adf-cli** for all production work. It's tested, published, and production-ready.
+
+---
+
+## 📝 Final Answer to Your Question
+
+### Your Question:
+> "If I understand it correctly the framework which integrates the 4 provided git repo frameworks as part of its core decision/recommendation tree, which is driven by an ai agentic interview-like questionaire to determine the best framework approach based on the users information value is all stored in the AgentDevFramework folder, and the npm cli installable tool to deploy and launch it, is in folder adf-cli, both in the root github folder (D:\Documents\GitHub), correct?"
+
+### My Answer:
+
+**Partially correct, but with important clarifications:**
+
+✅ **CORRECT:**
+- Both folders exist in `D:\Documents\GitHub\`
+- AgentDevFramework contains references to 4 framework repos (as git submodules)
+- adf-cli is the npm CLI tool
+- Both relate to the same methodology
+
+❌ **NEEDS CLARIFICATION:**
+- The 4 frameworks are **not** integrated "as part of core decision tree" in a runtime sense
+- The 4 frameworks were **studied and synthesized** into adf-cli's design
+- adf-cli **does not depend on** AgentDevFramework folder to run
+- adf-cli **is not** a deployment tool "for" AgentDevFramework
+- adf-cli **is** a standalone production CLI that embeds the methodology
+
+### More Accurate Description:
+
+**AgentDevFramework:**
+- Research repository with git submodules to 4 frameworks
+- Documentation of framework synthesis
+- Original scripts (not the CLI we built)
+- **Not required** for adf-cli to work
+
+**adf-cli:**
+- Standalone npm CLI tool (completely independent)
+- Implements the methodology discovered in AgentDevFramework research
+- AI-driven interview system (what we built)
+- Quality-based progress tracking (what we built)
+- Tool config generators (what we built)
+- Published to npm as `@iservu-inc/adf-cli`
+- **This is what we've been working on** (v0.1.0 → v0.3.0)
+
+### Bottom Line:
+We've been building **adf-cli** - a production-ready CLI tool that can be installed globally via npm and works independently of the AgentDevFramework repository. The two projects are related in concept but separate in execution.
+
+---
+
+**Created:** 2025-10-03
+**Purpose:** Complete project structure clarity
+**Location:** `adf-cli/.project/docs/PROJECT-STRUCTURE-EXPLANATION.md`

package/.project/docs/architecture/SYSTEM-DESIGN.md

@@ -58,7 +58,31 @@
                  ┌────────────┐    ┌───────────┐    ┌──────────────┐
                  │   PRP      │    │ Balanced  │    │    BMAD      │
                  │  Output    │    │  Output   │    │   Output     │
-                 └────────────┘    └───────────┘    └──────────────┘
+                 └────────┬───┘    └─────┬─────┘    └──────┬───────┘
+                          │              │                 │
+                          └──────────────┼─────────────────┘
+                                         │
+                                         ▼
+                                ┌─────────────────┐
+                                │  adf deploy     │
+                                │   (Command)     │
+                                └────────┬────────┘
+                                         │
+                        ┌────────────────┼────────────────┐
+                        │                │                │
+                        ▼                ▼                ▼
+                 ┌────────────┐   ┌───────────┐   ┌──────────────┐
+                 │ AGENTS.md  │   │ Windsurf  │   │   Cursor     │
+                 │ Generator  │   │ Generator │   │  Generator   │
+                 └────────────┘   └───────────┘   └──────────────┘
+                        │                │                │
+                        ▼                ▼                ▼
+                 ┌────────────┐   ┌───────────┐   ┌──────────────┐
+                 │ VS Code    │   │  Tool     │   │   Config     │
+                 │ Generator  │   │  Config   │   │   Files      │
+                 └────────────┘   │ Generator │   │  Generated   │
+                                  │  (Base)   │   └──────────────┘
+                                  └───────────┘
 ```
 
 ## Component Details
@@ -242,6 +266,103 @@ Total:               0-100 points
 - `architecture.md`: System architecture
 - `stories.md`: User stories
 
+### 8. Tool Configuration Generators (v0.3.0)
+
+**Responsibilities:**
+- Transform framework outputs into IDE-specific configurations
+- Generate universal AGENTS.md standard
+- Create tool-specific customizations
+- Support all 3 frameworks (PRP, Balanced, BMAD)
+
+**Base Class (tool-config-generator.js):**
+- Load framework outputs from session
+- Parse markdown sections
+- Extract template variables
+- Provide utility methods
+
+**AGENTS.md Generator (agents-md-generator.js):**
+- Universal AI agent configuration standard
+- Works with OpenAI Codex, Cursor, Windsurf, Google Jules, Factory
+- Supported by 20,000+ open-source projects
+- Always generated on deployment
+
+**Windsurf Generator (windsurf-generator.js):**
+- `.windsurfrules` - Legacy format (12K char limit compliant)
+- `.windsurf/rules/*.md` - Modern modular rules
+  - `project-context.md`
+  - `architecture.md`
+  - `coding-standards.md` (if applicable)
+- `.windsurf/workflows/*.md` - Cascade AI workflows
+  - `review-requirements.md`
+  - `implement-feature.md` (Balanced/BMAD only)
+
+**Cursor Generator (cursor-generator.js):**
+- `.cursor/rules` - Modern primary configuration
+- `.cursorrules` - Deprecation notice with migration path
+- `.cursor/mcp.json` - Model Context Protocol (prepared for future)
+- Custom modes: architect, implementer, reviewer
+
+**VS Code Generator (vscode-generator.js):**
+- `.github/copilot-instructions.md` - GitHub Copilot instructions
+- `.vscode/settings.json` - Custom chat modes
+  - Architect mode - System design focus
+  - Implementer mode - Feature implementation with TDD
+  - Reviewer mode - Code review against requirements
+- Preserves existing settings
+
+**Template Variables:**
+```javascript
+{
+  PROJECT_NAME,           // From metadata or directory
+  SESSION_ID,            // Session identifier
+  FRAMEWORK,             // rapid/balanced/comprehensive
+
+  // PRP
+  PRP_GOAL,
+  PRP_CONTEXT,
+  PRP_TECH_STACK,
+  PRP_IMPLEMENTATION,
+  PRP_VALIDATION,
+
+  // Balanced
+  CONSTITUTION_PRINCIPLES,
+  CONSTITUTION_CONSTRAINTS,
+  SPECIFICATION_OVERVIEW,
+  SPECIFICATION_ARCHITECTURE,
+  PLAN_TECH_STACK,
+  PLAN_CODE_STYLE,
+  TASKS_BREAKDOWN,
+
+  // BMAD
+  PRD_OVERVIEW,
+  PRD_GOALS,
+  PRD_TECH_REQUIREMENTS,
+  ARCHITECTURE_OVERVIEW,
+  ARCHITECTURE_COMPONENTS,
+  STORIES_LIST
+}
+```
+
+### 9. Deploy Command (deploy.js)
+
+**Responsibilities:**
+- Find latest completed session
+- Detect framework type
+- Generate AGENTS.md (always)
+- Generate tool-specific configurations
+- Deploy legacy agents (for backward compatibility)
+
+**Key Functions:**
+- `findLatestSession()`: Locate most recent session with outputs
+- `getFrameworkFromSession()`: Read framework from metadata
+- `deployToTool(tool)`: Orchestrate generation and deployment
+
+**Tool Support:**
+- `windsurf` - Generates Windsurf configs + AGENTS.md
+- `cursor` - Generates Cursor configs + AGENTS.md
+- `vscode` - Generates VS Code configs + AGENTS.md
+- Legacy tools still supported (kiro, trae, etc.)
+
 ## Data Flow
 
 ### New Session Flow