Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(phase-0): establish comprehensive documentation and automation system

Browse Source 
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.
This commit is contained in:
Data Warrior
2025-11-11 11:09:36 -07:00
parent 7e49d8c8d4
commit 0a131a296e
11 changed files with 4399 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

220
docs/GITEA/LLM-Gitea-Guidelines.md Normal file
View File

@@ -0,0 +1,220 @@
# LLM Guidelines for Working with Gitea
**Purpose**: Specific guidelines for AI assistants (LLMs) when working with Gitea-based projects like Tendril.
**Last Updated**: 2025-01-27
---
## Core Principles
1. **Always refer to "Gitea"** (not "GitHub") when the platform is Gitea
2. **Note compatibility** when discussing Gitea Actions (compatible with GitHub Actions)
3. **Use Gitea terminology** consistently
4. **Link to Gitea documentation** when referencing features
---
## Terminology Guidelines
### Correct Usage
✅ **Use These Terms**:
- "Gitea" - The platform
- "Gitea Actions" - CI/CD system
- "Gitea Runners" - CI/CD execution environment
- "Gitea instance" - Self-hosted Gitea server
- "Pull Request" or "PR" - Code review (same as GitHub)
- "Issues" - Bug/feature tracking (same as GitHub)
- "Repository" or "Repo" - Code storage (same as GitHub)
❌ **Avoid These Terms** (when referring to Gitea):
- "GitHub" - Wrong platform
- "GitHub Actions" - Should be "Gitea Actions" (but note compatibility)
- "GitHub Runners" - Should be "Gitea Runners"
- "GitHub repository" - Should be "Gitea repository"
### Compatibility Notes
When discussing workflows or Actions:
- ✅ "Gitea Actions workflows (compatible with GitHub Actions format)"
- ✅ "Gitea Actions uses the same YAML format as GitHub Actions"
- ✅ "Workflows use `.github/workflows/` directory (same as GitHub)"
---
## Documentation Standards
### When Creating Documentation
1. **Platform Reference**:
```markdown
This repository uses **Gitea** for version control and collaboration.
```
2. **Actions Reference**:
```markdown
This project uses **Gitea Actions** for CI/CD. Gitea Actions is compatible
with GitHub Actions, so workflows use the same YAML format and
`.github/workflows/` directory structure.
```
3. **Repository Links**:
```markdown
Repository: https://git.parkingmeter.info/Mycelium/tendril
```
### When Creating Workflow Files
1. **File Location**: `.github/workflows/` (same as GitHub)
2. **YAML Format**: Identical to GitHub Actions
3. **Documentation**: Reference as "Gitea Actions workflows"
4. **Comments**: Note compatibility if relevant
**Example**:
```yaml
# Gitea Actions workflow
# Compatible with GitHub Actions format
name: KB Lint
on:
push:
paths:
- 'kb/**/*.md'
```
### When Updating Cursor Rules
1. **Use "Gitea Actions"** in rules:
```markdown
#### When Gitea Actions workflows (`.github/workflows/*.yml`) are modified:
```
2. **Note compatibility**:
```markdown
**Note**: Gitea Actions is compatible with GitHub Actions, so workflows
use the same YAML format and `.github/` directory structure.
```
---
## Common Scenarios
### Scenario 1: Creating a New Workflow
**What to do**:
1. Create workflow in `.github/workflows/`
2. Use standard GitHub Actions YAML format
3. Document as "Gitea Actions workflow"
4. Note compatibility in documentation
5. Update `.github/CHANGELOG.md`
6. Update `.github/README.md`
**Example documentation**:
```markdown
### KB Lint Workflow
**File**: `.github/workflows/kb-lint.yml`
**Purpose**: Validates KB file naming and frontmatter
**Platform**: Gitea Actions (compatible with GitHub Actions format)
**Triggers**: Runs on push and pull requests when KB files change
```
### Scenario 2: Referencing Repository
**What to do**:
1. Use Gitea repository URL
2. Reference as "Gitea repository"
3. Link to Gitea instance
**Example**:
```markdown
**Repository**: https://git.parkingmeter.info/Mycelium/tendril
**Platform**: Gitea (self-hosted)
```
### Scenario 3: Discussing Features
**What to do**:
1. Reference Gitea features
2. Note similarities to GitHub when helpful
3. Link to Gitea documentation
**Example**:
```markdown
Gitea supports Pull Requests (similar to GitHub) and also provides
an AGit workflow alternative. For more information, see the
[Gitea documentation](https://docs.gitea.com/).
```
---
## File Structure Guidelines
### Workflow Files
- **Location**: `.github/workflows/`
- **Format**: YAML (same as GitHub Actions)
- **Naming**: `kebab-case.yml`
- **Documentation**: Reference as "Gitea Actions workflows"
### Documentation Files
- **Location**: `.github/` or project root
- **Content**: Use "Gitea" terminology
- **Links**: Link to Gitea documentation when relevant
### Cursor Rules
- **Location**: `.cursorrules` or `.cursor/rules/`
- **Content**: Use "Gitea Actions" (not "GitHub Actions")
- **Notes**: Include compatibility notes where relevant
---
## Checklist for LLMs
When working with Gitea-based projects:
- [ ] Use "Gitea" (not "GitHub") when referring to the platform
- [ ] Use "Gitea Actions" (not "GitHub Actions") but note compatibility
- [ ] Reference Gitea repository URLs correctly
- [ ] Link to Gitea documentation: `https://docs.gitea.com/`
- [ ] Note compatibility when discussing workflows
- [ ] Use `.github/workflows/` directory (same as GitHub)
- [ ] Use standard GitHub Actions YAML format for workflows
- [ ] Update `.github/CHANGELOG.md` when modifying workflows
- [ ] Update `.github/README.md` when adding workflows
- [ ] Use Gitea terminology consistently
---
## Quick Reference
### Repository Information
- **Platform**: Gitea (self-hosted)
- **Instance**: git.parkingmeter.info
- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
### Documentation Links
- **Gitea Docs**: https://docs.gitea.com/
- **Gitea Actions**: https://docs.gitea.com/usage/actions/
- **Gitea API**: https://docs.gitea.com/api/
### Key Points
1. Gitea is self-hosted (not GitHub)
2. Gitea Actions is compatible with GitHub Actions
3. Workflows use same format and directory structure
4. Terminology should reference "Gitea" consistently
---
**Location**: `docs/GITEA/LLM-Gitea-Guidelines.md`
**Related**: `docs/AGENT-GUIDELINES.md`, `.cursorrules`