More flexible artifacts

CHANGELOG.md

@@ -8,6 +8,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **File Linking Support**: Enhanced project documentation system to support linking existing files via symlinks
+  - `setup_project_docs` tool now accepts file paths in addition to template names
+  - Support for README.md, ARCHITECTURE.md, DESIGN.md, and other existing documentation files
+  - Automatic file detection and suggestion system for common documentation patterns
+  - Symlink creation in `.vibe/docs/` folder maintains standard paths while referencing existing files
+  - Mixed usage support: combine templates and file paths in same setup call
+  - Security validation prevents directory traversal attacks
+  - Multiple document types can reference the same source file (e.g., README.md for all types)
+- **"None" Template Support**: New "none" template option for users who prefer plan-file-only workflows
+  - Creates instructional placeholder documents that guide LLM to use plan file instead
+  - Granular control: disable specific document types while keeping others
+  - Cross-conversation persistence: choice survives across sessions
+  - Clear LLM instructions: "DO NOT EDIT THIS FILE" with plan file guidance
+- **Enhanced Tool Descriptions**: Comprehensive examples and usage guidance for file linking functionality
+- **Path Validation System**: Robust file path validation with security constraints
+- **File Detection Manager**: Pattern-based discovery of existing documentation files
+
+### Changed
+- `setup_project_docs` tool parameters now accept string values instead of strict enums
+- Enhanced tool descriptions with file path examples and common patterns
+- Project documentation system supports both template creation and file linking workflows
+
+### Technical
+- New `PathValidationUtils` class for secure file path validation
+- New `FileDetectionManager` class for pattern-based file discovery
+- Enhanced `ProjectDocsManager` with symlink creation and management capabilities
+- Extended `SetupProjectDocsHandler` with dual parameter validation (templates OR file paths)
+- Comprehensive integration tests for file linking functionality
+
 - **Project Documentation System**: Complete intelligent artifact management system
   - Dynamic template discovery from file system structure
   - Support for Arc42, EARS, Comprehensive, and Freestyle documentation templates

README.md

@@ -135,11 +135,62 @@ The user interacts normally with the LLM - the tool calls happen automatically i
 The project documentation system provides intelligent artifact management with:
 
 - **Dynamic Template Discovery**: Automatically discovers available templates from the file system
+- **File Linking Support**: Link existing documentation files (like README.md) instead of creating new ones
 - **Workflow Integration**: Workflows reference project documents contextually (e.g., `$ARCHITECTURE_DOC`, `$REQUIREMENTS_DOC`)
 - **Intelligent Setup Guidance**: Analyzes workflows to detect missing documents and provides targeted setup recommendations
 - **Multiple Template Types**: Support for Arc42, EARS, Comprehensive, and Freestyle documentation approaches
+- **Symlink Management**: Uses symbolic links to maintain standard paths while referencing existing files
 - **Zero Maintenance**: Add new templates without code changes - just drop files in the templates directory
 
+#### **File Linking Capabilities**
+
+The system now supports linking existing documentation files instead of only creating new structured documents:
+
+**Mixed Usage Examples:**
+```bash
+# Link existing README.md as requirements, create new architecture doc
+setup_project_docs({
+  architecture: "arc42",
+  requirements: "README.md", 
+  design: "docs/design.md"
+})
+
+# Use existing files for all document types
+setup_project_docs({
+  architecture: "ARCHITECTURE.md",
+  requirements: "README.md",
+  design: "README.md"  # Same file can serve multiple purposes
+})
+
+# Disable specific document types with "none" template
+setup_project_docs({
+  architecture: "arc42",
+  requirements: "none",     # Creates placeholder, uses plan file instead
+  design: "comprehensive"
+})
+
+# Mixed approach: templates, files, and disabled docs
+setup_project_docs({
+  architecture: "README.md",  # Link existing file
+  requirements: "ears",       # Use template
+  design: "none"              # Disable with placeholder
+})
+```
+
+**Supported File Patterns:**
+- `README.md`, `ARCHITECTURE.md`, `DESIGN.md`, `REQUIREMENTS.md`
+- Files in `docs/` folder: `docs/architecture.md`, `docs/requirements.md`
+- Absolute and relative file paths
+- Multiple document types can reference the same source file
+- **"none" template**: Creates placeholder that instructs LLM to use plan file instead
+
+**How It Works:**
+1. **Template OR File Path OR "none"**: Each parameter accepts template names, file paths, or "none"
+2. **Automatic Detection**: System detects existing documentation files and suggests them
+3. **Symlink Creation**: Creates symbolic links in `.vibe/docs/` pointing to existing files
+4. **Placeholder Creation**: "none" creates instructional placeholder for plan-file-only workflows
+5. **Standard Integration**: Workflows continue to work with standard document paths
+
 ### Review System
 
 The review system provides optional quality gates before phase transitions, ensuring thorough evaluation of work before proceeding to the next development phase.

resources/templates/architecture/none.md

@@ -0,0 +1,17 @@
+# Architecture Placeholder
+
+This is a placeholder document. The user has chosen not to maintain separate architecture documentation for this project.
+
+## INSTRUCTIONS FOR LLM
+
+**DO NOT EDIT THIS FILE**
+
+- Use the current development plan file to specify architecture decisions for ongoing development
+- Reference architecture information from the plan file context when needed
+- Focus architecture discussion in the plan file's "Key Decisions" and "Notes" sections
+- When architecture decisions are needed, document them in the plan file rather than here
+- This placeholder ensures the workflow variables work correctly while respecting the user's choice
+
+## User's Choice
+
+The user has explicitly chosen not to use dedicated architecture documentation for this project. Please respect this decision and work with the plan file for architecture-related information.

resources/templates/design/none.md

@@ -0,0 +1,17 @@
+# Design Placeholder
+
+This is a placeholder document. The user has chosen not to maintain separate design documentation for this project.
+
+## INSTRUCTIONS FOR LLM
+
+**DO NOT EDIT THIS FILE**
+
+- Use the current development plan file to specify design decisions for ongoing development
+- Reference design information from the plan file context when needed
+- Focus design discussion in the plan file's "Key Decisions" and implementation task sections
+- When design decisions are needed, document them in the plan file rather than here
+- This placeholder ensures the workflow variables work correctly while respecting the user's choice
+
+## User's Choice
+
+The user has explicitly chosen not to use dedicated design documentation for this project. Please respect this decision and work with the plan file for design-related information.

resources/templates/requirements/none.md

@@ -0,0 +1,17 @@
+# Requirements Placeholder
+
+This is a placeholder document. The user has chosen not to maintain separate requirements documentation for this project.
+
+## INSTRUCTIONS FOR LLM
+
+**DO NOT EDIT THIS FILE**
+
+- Use the current development plan file to specify requirements for ongoing development
+- Reference requirements from the plan file context when needed
+- Focus requirements discussion in the plan file's "Goal" and relevant task sections
+- When requirements clarification is needed, document them in the plan file rather than here
+- This placeholder ensures the workflow variables work correctly while respecting the user's choice
+
+## User's Choice
+
+The user has explicitly chosen not to use dedicated requirements documentation for this project. Please respect this decision and work with the plan file for requirements-related information.