Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
27 Commits 2 Branches 0 Tags
5b8bf621305f0bc752c43813fea9d3460b91b373
Commit Graph

4 Commits

Author SHA1 Message Date
Gitea Actions
197f44b4d3 docs: add issues capture system and KB documentation
Some checks failed
KB Lint / validate (push) Has been cancelled
Details 
This commit adds the issues capture system from PAIRS project and documents
it in the KB system, following all KB system rules for changelog and index
updates.

## What Was Added

### 1. Issues Capture System (docs/issues/)

**docs/issues/README.md** - System documentation:
- Purpose and workflow for quick issue capture
- File naming convention (YYYY-MM-DD--short-description.md)
- Issue types (bug, feature, insight, structural, improvement, question)
- Template fields and best practices
- Integration with Gitea platform
- Future automation possibilities

**docs/issues/template.md** - Issue file template:
- Minimal required fields (title, type, date, status)
- Optional fields (description, impact, notes, related)
- Gitea issue tracking section
- Simple, quick-capture format

**docs/issues/2025-11-11--gitea-runner-setup-request.md** - Moved from .github/:
- Gitea Actions runner configuration request
- Updated to match issue template format
- Includes type, date, status fields
- Ready for compilation to Gitea issue

### 2. KB Documentation Entry

**kb/02_systems/2025-11-11--issues-capture-system--note.md** - KB entry:
- Documents the issues capture system structure and workflow
- Explains quick capture process
- Describes compilation to Gitea issues
- Includes best practices and integration points
- Properly categorized in 02_systems/ (infrastructure/tooling)
- Complete frontmatter with all 18 required fields

### 3. KB System Updates

**kb/CHANGELOG.md** - Updated:
- Added entry for issues capture system documentation
- Date: 2025-11-11
- Documents KB file addition

**kb/_index.md** - Regenerated:
- Index updated via generate-index.sh script
- New KB file appears in 02_systems category
- Topics indexed: documentation, issue-tracking, workflow, gitea
- Tags indexed: issues, capture, documentation, gitea, workflow
- Summary updated with file count

## Why This Implementation

### Quick Issue Capture
   The issues capture system provides a lightweight staging area for capturing
   issues, insights, bugs, and features as you encounter them. This enables
   quick capture without the overhead of creating formal Gitea issues immediately.

### Markdown-Based Workflow
   Issues are captured as markdown files, making them easy to edit, version
   control, and review. This provides flexibility before committing to formal
   issue tracking.

### Later Compilation
   Issues can be batch-processed into Gitea issues when ready, allowing for
   review, prioritization, and grouping before creating formal issues.

### Documentation in KB
   The issues capture system is documented in the KB system, making it
   discoverable and providing reference material for the workflow.

## Technical Details

### File Structure

### Issue File Format

- **Naming**:
- **Template**: Minimal fields for quick capture
- **Status**: captured → reviewed → compiled
- **Integration**: Links to Gitea issues when compiled

### KB Entry Details

- **Category**: 02_systems (infrastructure, DevOps, tooling)
- **Type**: note
- **Topics**: documentation, issue-tracking, workflow, gitea
- **Tags**: issues, capture, documentation, gitea, workflow
- **Routing Confidence**: 0.95 (high confidence)

## Files Added/Modified

### Added
- docs/issues/README.md - Issues capture system documentation
- docs/issues/template.md - Issue file template
- docs/issues/2025-11-11--gitea-runner-setup-request.md - Runner setup request (moved from .github/)
- kb/02_systems/2025-11-11--issues-capture-system--note.md - KB documentation entry

### Modified
- kb/CHANGELOG.md - Added entry for new KB file
- kb/_index.md - Regenerated with new KB file indexed

## KB System Compliance

✅ KB file follows naming convention (YYYY-MM-DD--slug--type.md)
✅ KB file has complete frontmatter (all 18 required fields)
✅ KB file date matches filename date
✅ KB file type matches filename type
✅ KB changelog updated with entry
✅ KB index regenerated via script
✅ All changes committed together

## Related

- Source: PAIRS-for-the-Individual project (docs/issues/)
- KB System: kb/README.md
- KB Changelog: kb/CHANGELOG.md
- KB Index: kb/_index.md
- Gitea Documentation: docs/GITEA/
 2025-11-11 12:31:15 -07:00
Gitea Actions
6a4683022f docs(prompts): implement Phase 4 LLM Usage Guides Setup 
This commit implements the complete LLM Usage Guides system for the Tendril
project, establishing reusable prompt documents for AI-assisted workflows.

## What Was Implemented

### 1. Core Guide Documents

**docs/PROMPTS/LLM-Usage-Guide.md** - Comprehensive LLM execution instructions:
- Recognizing prompt documents (naming convention, structure, location)
- Step-by-step execution process (5 phases: recognize, gather info, execute, handle errors, validate)
- Information gathering requirements and best practices
- Error handling procedures and common error patterns
- Validation steps (pre-execution, during execution, post-execution)
- Providing feedback (progress updates, error reporting, completion summaries)
- Best practices for execution, communication, and quality
- Special instructions for Tendril-specific context
- Troubleshooting guide for common prompt execution issues
- Customized for Tendril project structure and Gitea platform

**docs/PROMPTS/Prompt-Creation-Guide.md** - Guide for creating effective prompts:
- Naming convention (NN-Descriptive-Name-Prompt.md format)
- Complete prompt structure template with all required sections
- Best practices for writing effective instructions
- Information gathering guidelines
- Error handling documentation standards
- Testing procedures for new prompts
- Common patterns (status check, search, sync patterns)
- Decision criteria for when to create new prompts
- Update procedures for existing prompts
- Comprehensive checklist for new prompts
- Examples customized for Tendril project
- References to Gitea-specific workflows and features

### 2. Initial Prompt Documents

**docs/PROMPTS/00-Project-Status-Check-Prompt.md** - Project status overview:
- Purpose: Check current status of all project phases
- Reads all phase blueprints in tendril/phases/
- Extracts phase status, deliverables, milestones
- Organizes by status (Complete, In Progress, Planned)
- Provides comprehensive status summary with counts
- Highlights issues or blockers
- Error handling for missing files, invalid formats
- Validation checklist for completion
- Customized for Tendril phase structure

**docs/PROMPTS/01-KB-Content-Search-Prompt.md** - KB system search:
- Purpose: Search KB system for relevant content
- Supports multiple search types: topics, tags, phase relevance, keywords
- Uses kb/_index.md for efficient searching
- Reads matching KB files and extracts metadata
- Presents organized search results with summaries
- Handles missing index, invalid criteria, empty results
- Provides helpful suggestions for refining searches
- Customized for Tendril KB structure and categories

**docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md** - Phase documentation synchronization:
- Purpose: Ensure phase documentation consistency
- Reads all four phase documents (blueprint, tasks, decisions, changelog)
- Compares and identifies discrepancies
- Syncs tasks.md with blueprint deliverables and Definition of Done
- Updates changelog.md with sync entry
- Reviews decisions.md for missing ADRs
- Verifies consistency across all documents
- Follows Cursor rules for phase documentation synchronization
- Error handling for missing files, format issues, unresolvable discrepancies
- Customized for Tendril phase structure and documentation system

## Why This Implementation

### Standardized AI Workflows
   LLM Usage Guides enable consistent, repeatable AI-assisted workflows. Instead
   of explaining the same tasks repeatedly, prompts provide standardized
   instructions that work reliably every time.

### Reusability and Efficiency
   Prompt documents can be dragged into Cursor chat sessions and executed
   immediately. This saves time and ensures tasks are performed consistently
   across different sessions and users.

### Quality and Reliability
   Well-structured prompts include validation checklists, error handling, and
   best practices. This reduces errors and ensures high-quality results.

### Knowledge Preservation
   Prompts document how to perform complex tasks, preserving institutional
   knowledge and making it accessible to anyone who needs to perform the task.

### Integration with Project Systems
   Prompts are designed to work with Tendril's phase documentation system, KB
   system, and Gitea workflows, providing seamless integration with existing
   project infrastructure.

## Technical Details

### Prompt Document Structure

All prompts follow a consistent structure:
1. **Title and Purpose** - Clear description of what the prompt does
2. **How to Use** - Instructions for using the prompt
3. **CRITICAL: Information Gathering** - Required information section
4. **Step-by-Step Process** - Phased execution instructions
5. **Error Handling** - Common issues and solutions
6. **Validation Checklist** - Completion verification
7. **Important Notes** - Critical instructions for AI assistant

### Naming Convention

Prompts follow strict naming:
- 00-09: Core system prompts
- 10-19: Phase management prompts
- 20-29: KB system prompts
- 30-39: Workflow and automation prompts
- 40-49: Documentation prompts
- 50+: Project-specific prompts

### Customization for Tendril

All prompts and guides are customized for:
- **Project Name**: Tendril (not "pairs" or placeholders)
- **Platform**: Gitea (not GitHub)
- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
- **Directory Structure**: tendril/phases/, kb/ with category directories
- **Workflows**: Gitea Actions (with GitHub Actions compatibility notes)

### Integration Points

Prompts integrate with:
- **Phase Documentation**: tendril/phases/phase-XX-name/ files
- **KB System**: kb/ directory with index and category structure
- **Workflows**: .github/workflows/ (Gitea Actions)
- **Documentation**: docs/ directory structure

## Files Added

- docs/PROMPTS/LLM-Usage-Guide.md - LLM execution instructions (~400 lines)
- docs/PROMPTS/Prompt-Creation-Guide.md - Prompt creation guide (~600 lines)
- docs/PROMPTS/00-Project-Status-Check-Prompt.md - Status check prompt (~180 lines)
- docs/PROMPTS/01-KB-Content-Search-Prompt.md - KB search prompt (~240 lines)
- docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md - Documentation sync prompt (~250 lines)

**Total**: 5 files, ~1,670 lines of prompt documentation

## Validation

All Phase 4 requirements met:
- ✅ LLM Usage Guide created and comprehensive
- ✅ Prompt Creation Guide created with complete template
- ✅ Three initial prompt documents created
- ✅ All prompts follow naming convention
- ✅ All prompts include required sections
- ✅ All files reference "Tendril" (42 references found)
- ✅ All files use "Gitea" terminology (10 references, no GitHub)
- ✅ Examples relevant to Tendril project structure
- ✅ Documentation is clear and actionable

## Next Steps

Phase 4 complete. LLM Usage Guides system is ready for use. Prompts can be
dragged into Cursor chat sessions to perform standardized tasks. Ready for
Phase 5: Validation and Testing.

## Related

- Phase 4 Plan: kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md
- Replication Guide: kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md
- Gitea LLM Guidelines: docs/GITEA/LLM-Gitea-Guidelines.md
 2025-11-11 12:25:52 -07:00
Data Warrior
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
Data Warrior
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