@iservu-inc/adf-cli 0.11.0 → 0.12.9

package/.adf/implementation-plan.md

@@ -0,0 +1,244 @@
+# ANDF Implementation Plan
+
+**Status:** In Progress
+**Started:** 2025-12-22
+**Target Completion:** TBD
+
+## Implementation Phases
+
+### ✅ Phase 0: Audit & Planning (COMPLETED)
+- [x] Audit current codebase
+- [x] Identify feature gaps
+- [x] Create implementation plan
+- [x] Assess backward compatibility
+
+---
+
+### 🔄 Phase 1: AGENTS.md Standard Compliance
+
+**Priority:** HIGH
+**Estimated Effort:** 3-4 hours
+**Files to Modify:**
+- `lib/generators/agents-md-generator.js`
+
+#### Tasks
+
+**1.1 Add YAML Frontmatter Support**
+- [ ] Add YAML parsing library (js-yaml) or use native string generation
+- [ ] Create frontmatter template with `name`, `description`, `tools`
+- [ ] Extract agent name/description from session metadata
+- [ ] Configure MCP tools (Archon, project_context)
+- **Validation:** YAML parses correctly, frontmatter renders in AGENTS.md
+
+**1.2 Add MCP Tools Configuration**
+- [ ] Create MCP tools template
+- [ ] Support Archon MCP server configuration
+- [ ] Support filesystem context server
+- [ ] Make MCP servers configurable per project
+- **Validation:** Tools section properly formatted in YAML
+
+**1.3 Restructure Content Sections**
+- [ ] Section 1: Operational Rules (High Priority)
+- [ ] Section 2: Build & Test Commands
+- [ ] Section 3: Project Structure
+- [ ] Section 4: Workflow Directives
+- [ ] Reference `.context/memory/architecture.md`
+- **Validation:** All sections present, properly formatted
+
+**Success Criteria:**
+- AGENTS.md follows ANDF standard format exactly
+- YAML frontmatter validates
+- All required sections present
+- References `.context/` directory
+- Backward compatible (no breaking changes)
+
+---
+
+### Phase 2: .context/ Directory Support
+
+**Priority:** HIGH
+**Estimated Effort:** 2-3 hours
+**Files to Modify:**
+- New: `lib/utils/context-manager.js`
+- `lib/generators/agents-md-generator.js`
+- `lib/commands/init.js`
+
+#### Tasks
+
+**2.1 Create .context/ Directory Structure**
+- [ ] Create `lib/utils/context-manager.js` utility
+- [ ] Implement `createContextStructure(projectPath)` function
+- [ ] Create `.context/memory/` directory
+- [ ] Create `.context/skills/` directory
+- [ ] Add `.gitignore` entries if needed
+- **Validation:** Directories created successfully
+
+**2.2 Generate architecture.md**
+- [ ] Extract architecture from PRP outputs
+- [ ] Extract architecture from Balanced spec
+- [ ] Extract architecture from BMAD architecture.md
+- [ ] Write to `.context/memory/architecture.md`
+- [ ] Include system overview, tech stack, patterns
+- **Validation:** architecture.md contains relevant content
+
+**2.3 Generate glossary.md**
+- [ ] Extract domain terms from session outputs
+- [ ] Format as glossary (term: definition)
+- [ ] Write to `.context/memory/glossary.md`
+- **Validation:** glossary.md created with terms
+
+**Success Criteria:**
+- `.context/` directory created on `adf deploy`
+- architecture.md contains extracted architecture info
+- glossary.md contains domain terms
+- AGENTS.md references `.context/memory/architecture.md`
+
+---
+
+### Phase 3: Zed Editor Support
+
+**Priority:** MEDIUM
+**Estimated Effort:** 3-4 hours
+**Files to Create:**
+- `lib/generators/zed-generator.js`
+**Files to Modify:**
+- `lib/generators/index.js`
+- `lib/commands/deploy.js`
+
+#### Tasks
+
+**3.1 Create Zed Generator**
+- [ ] Create `lib/generators/zed-generator.js`
+- [ ] Extend `ToolConfigGenerator` base class
+- [ ] Implement `generate()` method
+- [ ] Generate `.zed/settings.json` with:
+  - Agent configuration (default_model, feature_specific_models)
+  - Context servers (archon, project_context)
+  - Model parameters (temperature settings)
+  - Terminal environment variables
+- **Validation:** settings.json generates correctly
+
+**3.2 Generate Keymap**
+- [ ] Create keymap template
+- [ ] Generate `.zed/keymap.json`
+- [ ] Add agent switching shortcuts
+- **Validation:** keymap.json valid JSON
+
+**3.3 Implement Symlink Support**
+- [ ] Cross-platform symlink creation
+- [ ] Create `.zed/rules -> ../AGENTS.md`
+- [ ] Handle Windows vs Unix differences
+- [ ] Graceful fallback if symlinks fail (copy file instead)
+- **Validation:** Symlink works on Unix, copy works on Windows
+
+**3.4 Integration**
+- [ ] Add 'zed' to TOOLS in `deploy.js`
+- [ ] Export generator in `index.js`
+- [ ] Add tests for Zed generator
+- **Validation:** `adf deploy zed` works
+
+**Success Criteria:**
+- `adf deploy zed` creates complete configuration
+- Symlink created on Unix systems
+- File copy fallback on Windows
+- MCP servers configured
+- Agent switching keys mapped
+
+---
+
+### Phase 4: Antigravity Support
+
+**Priority:** MEDIUM
+**Estimated Effort:** 2 hours
+**Files to Create:**
+- `lib/generators/antigravity-generator.js`
+**Files to Modify:**
+- `lib/generators/index.js`
+- `lib/commands/deploy.js`
+
+#### Tasks
+
+**4.1 Create Antigravity Generator**
+- [ ] Create `lib/generators/antigravity-generator.js`
+- [ ] Extend `ToolConfigGenerator` base class
+- [ ] Implement `generate()` method
+- [ ] Generate `.antigravity/agents.yaml` with:
+  - Agent name and model
+  - Capabilities (file_system access to AGENTS.md and .context)
+  - System prompt referencing AGENTS.md
+- **Validation:** agents.yaml generates correctly
+
+**4.2 Integration**
+- [ ] Update TOOLS in `deploy.js` (already listed)
+- [ ] Add actual generator call
+- [ ] Export generator in `index.js`
+- [ ] Add tests
+- **Validation:** `adf deploy antigravity` works
+
+**Success Criteria:**
+- `adf deploy antigravity` creates `.antigravity/agents.yaml`
+- Configuration mounts AGENTS.md
+- File system access configured for .context/
+- System prompt instructs to read AGENTS.md on startup
+
+---
+
+### Phase 5: Testing & Validation
+
+**Priority:** HIGH
+**Estimated Effort:** 2-3 hours
+
+#### Tasks
+
+**5.1 Unit Tests**
+- [ ] Test AGENTS.md YAML frontmatter generation
+- [ ] Test .context/ directory creation
+- [ ] Test Zed generator
+- [ ] Test Antigravity generator
+- [ ] Test symlink creation/fallback
+
+**5.2 Integration Tests**
+- [ ] Test full deployment workflow
+- [ ] Test backward compatibility
+- [ ] Test on Windows/Linux/macOS
+
+**5.3 Manual Testing**
+- [ ] Create test project
+- [ ] Run `adf init --rapid`
+- [ ] Run `adf deploy zed`
+- [ ] Verify AGENTS.md format
+- [ ] Verify .context/ structure
+- [ ] Verify .zed/ configuration
+- [ ] Test in actual Zed editor
+
+**Success Criteria:**
+- All tests pass
+- No regressions in existing functionality
+- New features work as expected
+- Cross-platform compatibility verified
+
+---
+
+## Implementation Order
+
+1. **Start:** Phase 1.1 (YAML frontmatter) - Foundation for everything else
+2. **Next:** Phase 1.2 & 1.3 (Complete AGENTS.md standard)
+3. **Then:** Phase 2 (Create .context/ structure)
+4. **Then:** Phase 3 (Zed support)
+5. **Then:** Phase 4 (Antigravity support)
+6. **Finally:** Phase 5 (Testing & validation)
+
+## Rollback Plan
+
+If issues arise:
+1. All changes are in generators - easy to revert
+2. Feature flag: `ENABLE_ANDF=true` environment variable
+3. Existing AGENTS.md generation still works
+4. No changes to core interview/learning systems
+
+## Notes
+
+- All changes are backward compatible
+- Existing deployments continue to work
+- ANDF features are additive, not replacements
+- Can be released incrementally (phase by phase)

package/.adf/implementation-progress.md

@@ -0,0 +1,203 @@
+# ANDF Implementation Progress
+
+**Last Updated:** 2025-12-22
+**Status:** Phase 1 & 2 Complete ✅
+
+## Completed Work
+
+### ✅ Phase 0: Audit & Planning
+- [x] Audited current codebase against AGENTS.md specification
+- [x] Identified feature gaps
+- [x] Created comprehensive implementation plan
+- [x] Assessed backward compatibility (all changes are additive)
+
+### ✅ Phase 1: AGENTS.md Standard Compliance
+**Status:** COMPLETE & TESTED
+**Files Modified:**
+- `lib/generators/agents-md-generator.js` (major update)
+- `tests/agents-md-generator.test.js` (updated for new format)
+
+**What Was Implemented:**
+1. **YAML Frontmatter Support**
+   - Added `generateFrontmatter()` method
+   - Includes `name`, `description`, and `tools` fields
+   - Agent name varies by framework (Developer, Project Architect, Solutions Architect)
+   - Description extracted from tech stack
+
+2. **MCP Tools Configuration**
+   - `project_context` tool - accesses `.context/` via filesystem MCP server
+   - Optional `archon` tool - configurable via env var or metadata
+   - Proper YAML formatting with tool descriptions
+
+3. **Restructured Content Sections (ANDF-Compliant)**
+   - Section 1: Operational Rules (High Priority)
+   - Section 2: Build & Test Commands
+   - Section 3: Project Structure
+   - Section 4: Workflow Directives
+   - Section 5: Project Context/Constitution/Product Vision (varies by framework)
+   - Section 6: Key Context Files
+   - Section 7: AI Agent Instructions (detailed, numbered)
+
+**Format Example:**
+```markdown
+---
+name: Project Name Developer
+description: Expert developer specializing in...
+tools:
+  - name: project_context
+    command: npx
+    args: ["@modelcontextprotocol/server-filesystem",".context"]
+    description: Access project context files
+---
+
+# AGENTS.md - The Agent Manifest
+
+## 1. Operational Rules (High Priority)
+...
+```
+
+**Test Results:**
+```
+PASS tests/agents-md-generator.test.js
+  ✓ PRP Framework
+  ✓ Balanced Framework
+  ✓ BMAD Framework
+  ✓ Template Variables (2 tests)
+
+All 5 tests passing
+```
+
+### ✅ Phase 2: .context/ Directory Support
+**Status:** COMPLETE
+**Files Created:**
+- `lib/utils/context-manager.js` (new utility, 500+ lines)
+
+**Files Modified:**
+- `lib/commands/deploy.js` (integrated ContextManager)
+
+**What Was Implemented:**
+1. **ContextManager Utility Class**
+   - Creates `.context/` directory structure
+   - Generates `.context/memory/architecture.md`
+   - Generates `.context/memory/glossary.md`
+   - Creates `.context/README.md` explaining the structure
+
+2. **Architecture.md Generation**
+   - **PRP (Rapid):** Extracts from PRP sections (goal, context, blueprint)
+   - **Balanced:** Combines spec, plan, and constitution
+   - **BMAD:** Copies existing architecture.md or extracts from PRD
+   - Includes: Overview, Tech Stack, Design Decisions, Components, Security, Performance
+
+3. **Glossary.md Generation**
+   - Automatically extracts domain terms from interview transcripts
+   - Identifies capitalized terms and acronyms
+   - Generates alphabetically sorted glossary
+   - Supports manual additions
+
+4. **Integration with Deploy Command**
+   - `.context/` created before AGENTS.md generation
+   - Runs automatically on `adf deploy`
+   - Graceful error handling with warnings
+
+**Directory Structure Created:**
+```
+project-root/
+├── AGENTS.md              # With YAML frontmatter & ANDF sections
+└── .context/              # NEW!
+    ├── README.md          # Explains the directory
+    ├── memory/
+    │   ├── architecture.md  # Generated from session outputs
+    │   └── glossary.md      # Extracted from transcripts
+    └── skills/            # (empty, for future use)
+```
+
+**Integration Points:**
+- `deploy.js` now calls ContextManager before generating AGENTS.md
+- AGENTS.md references `.context/memory/architecture.md` in operational rules
+- All three frameworks (PRP, Balanced, BMAD) supported
+
+## Backward Compatibility
+
+✅ **100% Backward Compatible**
+- All changes are ADDITIVE
+- Existing `.windsurfrules`, `.cursorrules`, `.vscode/settings.json` unchanged
+- `.adf/` structure unchanged
+- Existing sessions/learning data unaffected
+- New features only activate on `adf deploy`
+
+## Pending Work
+
+### 🔄 Phase 3: Zed Editor Support (TODO)
+**Priority:** Medium
+**Estimated:** 3-4 hours
+
+**Tasks:**
+- [ ] Create `lib/generators/zed-generator.js`
+- [ ] Generate `.zed/settings.json` with MCP config
+- [ ] Generate `.zed/keymap.json`
+- [ ] Implement cross-platform symlink support (`.zed/rules -> ../AGENTS.md`)
+- [ ] Add 'zed' to TOOLS in deploy.js
+- [ ] Write tests
+
+### 🔄 Phase 4: Antigravity Support (TODO)
+**Priority:** Medium
+**Estimated:** 2 hours
+
+**Tasks:**
+- [ ] Create `lib/generators/antigravity-generator.js`
+- [ ] Generate `.antigravity/agents.yaml`
+- [ ] Configure to mount AGENTS.md
+- [ ] Update deploy.js to call generator
+- [ ] Write tests
+
+### 🔄 Phase 5: Final Testing (TODO)
+**Priority:** High
+**Estimated:** 2-3 hours
+
+**Tasks:**
+- [ ] Write unit tests for ContextManager
+- [ ] Integration tests for full deployment flow
+- [ ] Test on Windows/Linux/macOS
+- [ ] Manual testing in actual IDEs
+- [ ] Documentation updates
+
+## Impact Summary
+
+### New Capabilities
+1. **AGENTS.md Standard Compliance**
+   - Industry-standard format
+   - Auto-discovered by next-gen AI tools
+   - MCP server integration ready
+
+2. **.context/ Directory**
+   - Agent-accessible deep context
+   - Architectural knowledge preserved
+   - Domain terminology documented
+
+3. **Better AI Agent Guidance**
+   - Structured operational rules
+   - Clear build/test commands
+   - Explicit workflow directives
+   - Security and performance guidelines
+
+### Benefits
+- **For Users:** Better AI assistant behavior, more consistent code generation
+- **For AI Tools:** Standard format, predictable structure, MCP integration
+- **For Teams:** Shared architectural knowledge, documented terminology
+- **For Framework:** Future-proof, industry-aligned, extensible
+
+## Technical Debt
+None introduced. All code follows existing patterns and conventions.
+
+## Next Steps
+1. Complete Phase 3 (Zed) if Zed support is priority
+2. Complete Phase 4 (Antigravity) if Antigravity support is priority
+3. OR skip to Phase 5 (Testing) to validate and ship Phase 1 & 2
+4. Update CHANGELOG.md and README.md
+5. Release as v0.12.0 (minor version bump for new features)
+
+## Notes
+- All changes validated with syntax checks
+- AGENTS.md generator tests updated and passing
+- Deploy command tested for syntax errors
+- Ready for integration testing with actual ADF sessions