@iservu-inc/adf-cli 0.14.6 → 0.17.0

package/.project/docs/designs/CUSTOM-ARTIFACT-UPLOAD.md

@@ -0,0 +1,259 @@
+# Custom Artifact Upload Feature
+
+## Overview
+
+Allow users to import existing markdown documentation (PRDs, design docs, specifications, architecture documents) from projects that have already undergone formal artifact generation outside of ADF's built-in frameworks (PRP, Balanced, BMAD).
+
+## Problem Statement
+
+Many projects already have:
+- Product Requirements Documents (PRDs) from Confluence, Notion, or Google Docs
+- Architecture Decision Records (ADRs)
+- Technical Design Documents (TDDs)
+- API Specifications (OpenAPI/Swagger converted to markdown)
+- User Story documents from Jira/Linear exports
+- Custom specification formats from enterprise tools
+
+Currently, ADF requires users to go through the full interview process even when comprehensive documentation already exists. This creates friction for teams with established documentation workflows.
+
+## Solution
+
+Add an `adf import` command that:
+1. Accepts one or more markdown files as input
+2. Categorizes them into artifact types (PRD, Architecture, Stories, Tasks, Custom)
+3. Creates a synthetic session with the imported artifacts
+4. Makes them available for deployment to any supported tool
+
+## Command Interface
+
+```bash
+# Import single file
+adf import ./docs/PRD.md
+
+# Import multiple files
+adf import ./docs/PRD.md ./docs/architecture.md ./docs/tasks.md
+
+# Import entire directory
+adf import ./docs/
+
+# Import with explicit type mapping
+adf import ./docs/PRD.md --type prd
+adf import ./docs/design.md --type architecture
+adf import ./docs/backlog.md --type stories
+
+# Import with custom artifact type
+adf import ./docs/compliance.md --type custom --name "Compliance Requirements"
+
+# Interactive mode (prompts for type of each file)
+adf import ./docs/*.md --interactive
+```
+
+## Artifact Type Detection
+
+### Auto-Detection Heuristics
+
+The system will attempt to auto-detect artifact types based on:
+
+1. **Filename patterns:**
+   - `*prd*`, `*requirements*`, `*product-req*` → PRD
+   - `*arch*`, `*design*`, `*technical*`, `*system*` → Architecture
+   - `*stories*`, `*user-stories*`, `*backlog*` → Stories
+   - `*tasks*`, `*implementation*`, `*todo*`, `*work-items*` → Tasks
+   - `*spec*`, `*specification*` → Specification
+   - `*constitution*`, `*guidelines*`, `*standards*` → Constitution
+
+2. **Content analysis (first 500 lines):**
+   - Headers containing "Requirements", "User Stories", "Architecture"
+   - Presence of story formats (As a... I want... So that...)
+   - Task list patterns (- [ ], checkboxes, numbered implementation steps)
+   - Technical diagrams (mermaid, plantuml references)
+
+3. **Frontmatter metadata:**
+   ```yaml
+   ---
+   type: prd
+   title: Product Requirements Document
+   version: 1.0
+   ---
+   ```
+
+### Supported Artifact Types
+
+| Type | Description | Maps To |
+|------|-------------|---------|
+| `prd` | Product Requirements Document | `outputs/prd.md` |
+| `architecture` | System/Technical Architecture | `outputs/architecture.md` |
+| `stories` | User Stories / Backlog | `outputs/stories.md` |
+| `tasks` | Implementation Tasks | `outputs/tasks.md` |
+| `specification` | Feature Specification | `outputs/specification.md` |
+| `constitution` | Quality Standards/Guidelines | `outputs/constitution.md` |
+| `plan` | Technical/Project Plan | `outputs/plan.md` |
+| `prp` | Agent-Native PRP Document | `outputs/prp.md` |
+| `custom` | Custom artifact (user-named) | `outputs/custom/{name}.md` |
+
+## Session Creation
+
+Imported artifacts create a synthetic session:
+
+```
+.adf/sessions/{timestamp}_imported/
+├── _metadata.json
+│   {
+│     "framework": "imported",
+│     "importedAt": "2026-01-21T...",
+│     "sourceFiles": ["./docs/PRD.md", "./docs/arch.md"],
+│     "artifactTypes": ["prd", "architecture"],
+│     "projectPath": "/path/to/project"
+│   }
+├── _progress.json
+│   {
+│     "status": "completed",
+│     "importedArtifacts": 2
+│   }
+├── outputs/
+│   ├── prd.md              # Copied/normalized from source
+│   ├── architecture.md     # Copied/normalized from source
+│   └── custom/
+│       └── compliance.md   # Custom artifacts in subdirectory
+└── sources/
+    ├── original_PRD.md     # Original files preserved
+    └── original_arch.md
+```
+
+## Content Normalization
+
+Imported files undergo light normalization:
+
+1. **Header standardization:** Ensure H1 title exists
+2. **Frontmatter injection:** Add ADF metadata if missing
+3. **Section markers:** Add section IDs for deployment parsing
+4. **Link resolution:** Convert relative links to absolute where possible
+5. **Image handling:** Copy referenced images to session directory
+
+### Normalization Example
+
+**Input:**
+```markdown
+# My PRD
+
+## Overview
+This document describes...
+```
+
+**Output:**
+```markdown
+---
+adf_type: prd
+adf_imported: true
+adf_source: ./docs/PRD.md
+adf_imported_at: 2026-01-21T10:30:00Z
+---
+
+# My PRD
+
+<!-- adf:section:overview -->
+## Overview
+This document describes...
+```
+
+## Integration with Deploy
+
+Imported sessions are treated identically to interview-generated sessions:
+
+```bash
+# After import
+adf import ./docs/PRD.md ./docs/architecture.md
+
+# Deploy works normally
+adf deploy windsurf
+adf deploy cursor
+adf deploy --all
+```
+
+The deploy command:
+1. Finds the latest session (imported or interview-generated)
+2. Loads outputs from the session
+3. Generates tool-specific configurations
+
+## Merge with Existing Sessions
+
+Users can augment an existing interview session with additional artifacts:
+
+```bash
+# Add architecture doc to existing session
+adf import ./docs/architecture.md --session latest
+
+# Add to specific session
+adf import ./docs/architecture.md --session 20260115_120000_balanced
+```
+
+## Implementation Plan
+
+### Phase 1: Core Import Command
+- [ ] Create `lib/commands/import.js`
+- [ ] Implement file reading and validation
+- [ ] Add artifact type detection heuristics
+- [ ] Create synthetic session structure
+- [ ] Basic content normalization
+
+### Phase 2: Enhanced Detection
+- [ ] Add content-based type detection
+- [ ] Support frontmatter parsing
+- [ ] Implement confidence scoring for type detection
+- [ ] Add `--interactive` mode for manual type selection
+
+### Phase 3: Deployment Integration
+- [ ] Update `ToolConfigGenerator` to handle imported sessions
+- [ ] Ensure all generators support `framework: "imported"`
+- [ ] Test deployment across all 12+ supported tools
+
+### Phase 4: Advanced Features
+- [ ] Directory scanning with glob patterns
+- [ ] Session merging (`--session` flag)
+- [ ] Image and asset handling
+- [ ] Link resolution and validation
+- [ ] Export back to original format (round-trip)
+
+## CLI Help Text
+
+```
+Usage: adf import [options] <files...>
+
+Import existing markdown documentation into ADF
+
+Arguments:
+  files                    Markdown files or directories to import
+
+Options:
+  -t, --type <type>        Artifact type (prd, architecture, stories, tasks, spec, custom)
+  -n, --name <name>        Custom artifact name (used with --type custom)
+  -s, --session <id>       Merge into existing session (use 'latest' for most recent)
+  -i, --interactive        Prompt for type of each file
+  --no-normalize           Skip content normalization
+  --dry-run                Show what would be imported without creating session
+  -h, --help               Display help for command
+
+Examples:
+  $ adf import ./docs/PRD.md
+  $ adf import ./docs/*.md --interactive
+  $ adf import ./design.md --type architecture
+  $ adf import ./compliance.md --type custom --name "Compliance Requirements"
+  $ adf import ./docs/stories.md --session latest
+```
+
+## Success Criteria
+
+1. Users can import any markdown file as an ADF artifact
+2. Auto-detection correctly identifies common artifact types (>80% accuracy)
+3. Imported sessions deploy successfully to all supported tools
+4. Original files are preserved in `sources/` directory
+5. Merge with existing sessions works without data loss
+6. `--dry-run` provides accurate preview of import results
+
+## Future Considerations
+
+- Support for non-markdown formats (PDF, DOCX, HTML) via conversion
+- Integration with external tools (Notion API, Confluence API, Jira export)
+- AI-assisted type detection and content summarization
+- Bidirectional sync with source documents
+- Version tracking for re-imported documents

package/.project/docs/designs/LEARNING-RULES-EXCHANGE.md

@@ -0,0 +1,77 @@
+# Design Specification: Learning Rules Exchange (Export/Import)
+
+## 1. Overview
+The Learning Rules Exchange system allows developers to share AI-learned preferences and skip patterns across team members or different environments. By exporting high-confidence rules to a portable JSON format, teams can standardize their AI-assisted interview experience.
+
+## 2. Data Structure
+
+### 2.1 Rule Export Format (JSON)
+```json
+{
+  "version": "1.0",
+  "metadata": {
+    "exportedBy": "String",
+    "exportedAt": "ISO-8601 Timestamp",
+    "projectType": "String (optional)",
+    "ruleCount": "Number",
+    "sourceFrameworks": ["Array of Strings"]
+  },
+  "rules": [
+    {
+      "id": "String (UUID)",
+      "questionId": "String",
+      "questionText": "String",
+      "category": "String",
+      "confidence": "Number (0-100)",
+      "type": "String (consistent_skip|category_skip|framework_skip)",
+      "recommendation": "String",
+      "origin": {
+        "sessionsAnalyzed": "Number",
+        "createdAt": "Timestamp"
+      }
+    }
+  ]
+}
+```
+
+## 3. Core Features
+
+### 3.1 Export Process
+- **Filter**: Only export high-confidence rules (default ≥75%).
+- **Metadata**: Attach environment context (ADF version, project type) to help importers understand relevance.
+- **Atomic Save**: Generate a single file (e.g., `adf-rules-2026-01-13.json`).
+
+### 3.2 Import Process & Merge Strategies
+When importing, users must choose how to handle conflicts with existing local rules:
+
+1. **Replace (Overwrite)**: Deletes all local rules and replaces them with the imported set.
+2. **Merge (Append Unique)**: Adds new rules from the file. If a rule for the same `questionId` exists, it keeps the one with the higher confidence score.
+3. **Skip Duplicates**: Only adds rules for questions that don't already have a local rule.
+
+### 3.3 Validation & Security
+- **Schema Validation**: Verify JSON structure before parsing.
+- **Sanitization**: Strip any potential script injection in string fields (questionText, recommendation).
+- **Provenance**: Track that a rule was "imported" in its local metadata to allow filtering/removal later.
+
+## 4. CLI Interface
+
+### 4.1 Integration into `adf config`
+**Learning System Menu additions:**
+- `[ ] Export Learned Rules`: Prompts for destination path.
+- `[ ] Import Rules from File`: Prompts for file path and merge strategy.
+
+### 4.2 User Experience
+- **Summary Before Import**: Show "Found 15 rules. 10 new, 5 existing. Strategy: Merge."
+- **Confirmation**: "Apply these rules to your learning system? (y/n)"
+
+## 5. Implementation Plan
+
+1. **Exporter**: `lib/learning/rules-exporter.js`
+   - Logic to extract from `storage.js` and format JSON.
+2. **Importer**: `lib/learning/rules-importer.js`
+   - Logic to parse, validate, and apply merge strategies.
+3. **UI Integration**: `lib/learning/learning-manager.js`
+   - Add menu items and prompt logic.
+
+---
+*Status: DESIGN COMPLETE*