Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
26 Commits 2 Branches 0 Tags
197f44b4d358b8c9fee52d299c783c0fb2671578
Commit Graph
6 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
datawarrior db003786f9 docs(phases): add Phase 3-6 plans and update Phase 2 plan 
This commit adds comprehensive plan documents for all remaining phases
of the project setup system replication:

## Phase Plans Added

### Phase 2 Plan (Updated)
- KB System Setup plan document
- Already implemented in previous commit
- Plan document now tracked in repository

### Phase 3 Plan (New)
- Gitea Actions Workflows Setup
- Covers .github/ documentation and workflow creation
- KB lint and KB index update workflows
- Customized for Tendril and Gitea platform

### Phase 4 Plan (New)
- LLM Usage Guides Setup
- LLM-Usage-Guide.md and Prompt-Creation-Guide.md
- Initial prompt documents
- Customized for Tendril project

### Phase 5 Plan (New)
- Validation and Testing
- Comprehensive testing procedures
- Test scenarios for all system components
- Troubleshooting guide

### Phase 6 Plan (New)
- Customization and Final Verification
- Project name and terminology verification
- Directory structure verification
- Final documentation review
- System integration verification

## Plan Structure

All plans follow consistent structure:
- Overview and current state
- Detailed task breakdown
- Customizations for Tendril
- Files to create
- Dependencies and success criteria
- Validation checklists
- Notes and references

## Customizations

All plans are customized for:
- Tendril project (not "pairs")
- Gitea platform (not GitHub)
- Tendril-specific directory structure
- Gitea Actions (with GitHub Actions compatibility notes)

## Files Added

- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-2-PLAN.md (5.0KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-3-PLAN.md (13KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md (8.1KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-5-PLAN.md (12KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-6-PLAN.md (11KB)

Total: 5 phase plan documents, ~49KB of planning documentation
 2025-11-11 11:50:01 -07:00
datawarrior aecc370e1d docs(kb): implement Phase 2 KB System Setup 
This commit implements the complete Knowledge Base (KB) system for the Tendril
project, establishing a structured, LLM-friendly system for capturing and
organizing external information that informs project development.

## What Was Implemented

### 1. KB System Documentation (kb/README.md)
   - Comprehensive documentation explaining the KB system's purpose and structure
   - Directory structure explanation with all 8 category directories
   - File naming schema: YYYY-MM-DD--slug--type.md with regex validation
   - Complete frontmatter schema documentation (18 required fields for Tendril)
   - Routing decision tree for categorizing content
   - Routing confidence system (0.00-1.00 scale) with policy for low-confidence items
   - Usage guidelines for creating and managing KB files
   - Integration notes with phase documentation system
   - Index generation and changelog update procedures

### 2. KB File Templates (kb/_templates/)
   Created three template files with complete frontmatter:

   - note.md: General notes template with draft status default
   - decision.md: ADR-style decision template with active status default
   - howto.md: How-to guide template with active status default

   All templates include:
   - All 18 required frontmatter fields (base + Tendril-specific)
   - Placeholder syntax (${VARIABLE}) for easy customization
   - Appropriate default values (routing_confidence, status, etc.)
   - Template-specific content sections
   - Customized for Tendril project (project: ["tendril"])

### 3. KB Ingestion Prompt (kb/_guides/KB_INGEST_PROMPT.md)
   Complete system prompt for LLM-assisted KB ingestion:

   - System instructions for content analysis and routing
   - Classification and routing rules for all 8 categories
   - Routing decision tree with 9-step decision process
   - Routing confidence assessment guidelines
   - File naming standards with examples and validation
   - Complete frontmatter requirements documentation
   - JSON output format specification
   - Quality and style guidelines
   - Safety constraints (NEVER/ALWAYS rules)
   - Validation checklist
   - Completion summary format with mandatory index/changelog updates

### 4. Index Generation Script (kb/scripts/generate-index.sh)
   Bash script for automatic KB index generation:

   - Scans all KB files in category directories (01_projects through 08_archive)
   - Excludes special directories (_guides, _templates, _inbox, _review_queue)
   - Extracts YAML frontmatter from each KB file
   - Parses metadata fields (title, date, type, summary, topics, tags, phases)
   - Generates kb/_index.md with:
     * File listing organized by category
     * Topics index (all unique topics with file references)
     * Tags index (all unique tags with file references)
     * Phase relevance index (files organized by phase)
     * Summary statistics
   - Compatible with Windows (Git Bash) and Unix systems
   - Uses temporary files for cross-platform compatibility
   - Handles errors gracefully (missing frontmatter, invalid files)
   - Script is executable (chmod +x)

### 5. KB Changelog (kb/CHANGELOG.md)
   Change tracking for KB system:

   - Initial entry documenting Phase 2 setup
   - Date-based format: ## [YYYY-MM-DD] KB System Setup
   - Lists all files created during setup
   - Notes about customization for Tendril project

### 6. Initial Index (kb/_index.md)
   Auto-generated searchable index:

   - Generated by running generate-index.sh
   - Currently empty (no KB files exist yet)
   - Ready to be populated as KB files are added
   - Includes proper structure for all index sections

## Why This Implementation

### Structured Knowledge Capture
   The KB system provides a lightweight staging area for external information
   (Pulse Daily chats, ideas, notes, research) that may inform Tendril project
   development. Unlike formal phase documentation, KB entries capture informal
   knowledge that complements the structured phase blueprints.

### LLM-Friendly Design
   The system is designed for LLM-assisted ingestion and management:
   - Clear routing decision tree enables automated classification
   - Confidence scoring allows human review of uncertain routing
   - Complete frontmatter ensures rich metadata for searchability
   - JSON output format enables automated file creation

### Searchability and Discovery
   The automatic index generation creates multiple access paths:
   - By category (for browsing related content)
   - By topic (for finding content on specific subjects)
   - By tag (for cross-cutting categorization)
   - By phase relevance (for finding content related to specific phases)

### Integration with Phase Documentation
   KB decisions complement phase-specific ADRs, KB research informs phase
   planning, and KB playbooks provide operational guides. The phase_relevance
   field creates explicit links between KB content and project phases.

### Project Customization
   All files are customized for Tendril:
   - Project name: "tendril" (replaced "pairs" references)
   - Default project field: ["tendril"]
   - Path references updated for Tendril structure
   - Gitea Actions noted (not GitHub Actions) for Phase 3

## Technical Details

### Frontmatter Schema (18 Fields)
   Base fields (14): title, date, author, source, project, topics, tags, type,
   status, routing_hint, proposed_path, routing_confidence, related, summary

   Tendril-specific (4): captured_at, source_type, related_projects,
   phase_relevance

   Optional (2): key_takeaways, action_candidates

### File Naming Pattern
   Regex: ^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$

   Components: Date (YYYY-MM-DD) + Slug (3-8 words, no stop-words) + Type

### Routing Confidence Policy
   - >= 0.60: File goes to proposed_path
   - < 0.60: File goes to _review_queue/ (with proposed_path in frontmatter)

## Next Steps

Phase 2 complete. Ready for Phase 3: Gitea Actions Workflows configuration.

## Files Added

- kb/README.md (290 lines)
- kb/_templates/note.md
- kb/_templates/decision.md
- kb/_templates/howto.md
- kb/_guides/KB_INGEST_PROMPT.md (~400 lines)
- kb/scripts/generate-index.sh (executable)
- kb/CHANGELOG.md
- kb/_index.md (auto-generated)
 2025-11-11 11:43:52 -07:00
datawarrior 03db6efeb8 docs: reorganize project structure and add Gitea platform context 
This commit implements a comprehensive reorganization of project documentation
and adds explicit Gitea platform context throughout the project.

## Documentation Reorganization

### File Moves (Content Preserved)
- Moved CURSOR_WINDOWS_SETUP.md to kb/_guides/ for better organization
- Moved docs/PHASE-UPDATES/ to kb/_guides/PROJECT-SETUP-GUIDE/:
  - COMPLETE-SYSTEM-REPLICATION-GUIDE.md
  - PHASE-0-GITEA-UPDATES.md
  - README.md
- Added new file: kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md

**Reason**: Consolidate project setup and configuration guides into the
knowledge base structure for better discoverability and organization.

### New Phase Documentation Structure
Created tendril/phases/ directory with structured phase documentation:
- phase-00-foundation/: blueprint, changelog, decisions, tasks
- phase-01-testing-validation/: blueprint, changelog, decisions, tasks

**Reason**: Establish consistent phase documentation structure following
project guidelines for phase management and tracking.

## Gitea Platform Context Integration

### .cursorrules Updates
- Added comprehensive Gitea platform context section
- Added Gitea documentation references for workflows and platform questions
- Added platform terminology guidelines (Gitea vs GitHub)
- Added references to docs/GITEA/ documentation throughout rules

**Reason**: Ensure all AI agents and contributors use correct Gitea terminology
and have clear guidance on where to find Gitea-specific documentation.

### Documentation Path Updates
- CONTRIBUTING.md: Updated CURSOR_WINDOWS_SETUP.md path reference
- docs/AGENT-GUIDELINES.md: Updated path references to moved documentation
- PROJECT_STATUS.md: Updated comment to mention Gitea Actions

**Reason**: Maintain link integrity after file reorganization and ensure
documentation references point to correct locations.

## Impact and Benefits

1. **Better Organization**: Documentation is now organized in logical
   structures (kb/ for knowledge base, tendril/phases/ for phase docs)

2. **Clear Platform Context**: Explicit Gitea platform references prevent
   confusion with GitHub terminology and provide clear documentation paths

3. **Consistent Structure**: Phase documentation follows standardized format
   (blueprint, changelog, decisions, tasks) for easier maintenance

4. **Improved Discoverability**: Guides consolidated in kb/_guides/ make it
   easier to find setup and configuration information

All file moves preserve content - no information was lost in this reorganization.
 2025-11-11 11:38:44 -07:00
datawarrior 0a131a296e feat(phase-0): establish comprehensive documentation and automation system 
Phase 0: Foundation & Cursor Rules Setup - Complete

This commit establishes the foundation for a comprehensive documentation and
project management system for Tendril, following best practices from the
COMPLETE-SYSTEM-REPLICATION-GUIDE.md.

## What Was Created

### 1. Cursor Rules System (.cursorrules)
- Comprehensive rules for AI agent behavior in Cursor IDE
- Phase documentation synchronization rules (auto-update changelog, tasks, decisions)
- KB (Knowledge Base) ingestion and routing rules
- Gitea Actions workflow maintenance rules
- README maintenance rules
- File deletion protection rules
- Customized for Tendril project with Gitea platform

### 2. Directory Structure
- tendril/phases/ - Phase-based project management structure
- kb/ - Knowledge Base system with 8 categories:
  * 01_projects/tendril/ - Project-specific notes
  * 02_systems/ - Infrastructure/tooling
  * 03_research/ - Informal research
  * 04_design/ - Product specs/UX
  * 05_decisions/ - Project-level ADRs
  * 06_glossary/ - Terms/acronyms
  * 07_playbooks/ - How-to guides
  * 08_archive/ - Superseded content
  * Special directories: _guides/, _templates/, _inbox/, _review_queue/, scripts/
- .github/workflows/ - Gitea Actions workflows (compatible with GitHub Actions)
- docs/PROMPTS/ - LLM usage guides

### 3. Agent Guidelines (docs/AGENT-GUIDELINES.md)
- Comprehensive guide for AI agents working on Tendril
- Documents project structure, workflows, and conventions
- Mandatory workflows and critical rules
- Project-specific context (Rust/WASM, Zed extension)
- Links to all documentation systems

### 4. Gitea Documentation (docs/GITEA/)
Complete documentation suite for working with Gitea:
- README.md - Overview and quick reference
- Gitea-Basics.md - Core concepts, features, differences from GitHub
- Gitea-Actions-Guide.md - CI/CD guide with compatibility notes
- Gitea-Workflows.md - Common workflows and best practices
- Gitea-API-Reference.md - API differences and usage
- LLM-Gitea-Guidelines.md - LLM-specific guidelines and terminology

### 5. Phase Updates Documentation (docs/PHASE-UPDATES/)
- COMPLETE-SYSTEM-REPLICATION-GUIDE.md - Complete replication guide
- PHASE-0-GITEA-UPDATES.md - Documents Gitea-specific updates
- README.md - Directory overview and navigation

## Why This Was Done

1. **Establish AI-Friendly Documentation System**
   - Enables consistent AI agent behavior across the project
   - Provides clear guidelines for documentation maintenance
   - Ensures automated synchronization of related documents

2. **Platform-Specific Adaptation (Gitea)**
   - Tendril uses self-hosted Gitea, not GitHub
   - Gitea Actions is compatible with GitHub Actions but needs proper documentation
   - Ensures all references use correct terminology (Gitea vs GitHub)

3. **Foundation for Phase-Based Management**
   - Sets up structure for phase documentation system
   - Prepares for KB system implementation
   - Establishes automation workflows foundation

4. **Knowledge Management**
   - KB system structure ready for capturing project knowledge
   - Templates and guides prepared for future use
   - Index generation system prepared

## How It Benefits the Project

### 1. Automated Documentation Synchronization
- When phase blueprints are modified, related documents (changelog, tasks, decisions)
  are automatically checked and updated
- Reduces manual synchronization errors
- Ensures consistency across all phase documents

### 2. AI Agent Consistency
- Cursor rules ensure all AI interactions follow the same patterns
- Clear guidelines prevent inconsistent documentation
- Automated checks ensure nothing is missed

### 3. Gitea Platform Understanding
- Comprehensive Gitea documentation helps LLMs understand the platform
- Correct terminology prevents confusion (Gitea vs GitHub)
- Workflow compatibility clearly documented

### 4. Scalable Structure
- Phase-based system supports long-term project management
- KB system ready for knowledge capture and organization
- Automation workflows prepared for CI/CD

### 5. Developer Experience
- Clear documentation structure makes onboarding easier
- Automated workflows reduce manual maintenance
- Consistent patterns across all documentation

### 6. Future-Proof Foundation
- Structure supports future phases (1-6)
- KB system ready for knowledge capture
- Automation system ready for workflow implementation

## Technical Details

### Gitea Actions Compatibility
- Gitea Actions uses same YAML format as GitHub Actions
- Same .github/workflows/ directory structure
- Workflows are largely interchangeable
- Documentation notes compatibility throughout

### File Organization
- All documentation organized in docs/ directory
- Phase updates tracked in docs/PHASE-UPDATES/
- Gitea-specific docs in docs/GITEA/
- Agent guidelines in docs/AGENT-GUIDELINES.md

### Cursor Rules Customization
- Project name: Tendril
- Phase directory: tendril/phases/
- KB project: tendril
- Platform: Gitea (self-hosted)

## Next Steps

Phase 0 is complete. Ready for:
- Phase 1: Phase Documentation System setup
- Phase 2: KB System implementation
- Phase 3: Gitea Actions workflows
- Phase 4: LLM Usage Guides
- Phase 5: Documentation migration
- Phase 6: Validation and testing

## Files Added

- .cursorrules (root)
- docs/AGENT-GUIDELINES.md
- docs/GITEA/ (6 files)
- docs/PHASE-UPDATES/ (3 files)
- Directory structures for phases, KB, workflows, and prompts

All files validated with no linter errors.
 2025-11-11 11:09:36 -07:00
datawarrior 7e49d8c8d4 Docs: Add Windows Cursor development environment setup guide 2025-11-11 10:33:54 -07:00
datawarrior cd73dda1f2 Docs: Add comprehensive contributing guide and update README 
- Add CONTRIBUTING.md with full development workflow documentation
- Document branch naming conventions (feature/, docs/, fix/, etc.)
- Add documentation standards and guidelines
- Establish PR process and review criteria
- Update README.md Contributing section to reference new guide
- Prepare foundation for documentation restructuring work
 2025-11-11 10:29:47 -07:00