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

286
docs/GITEA/Gitea-Actions-Guide.md Normal file
View File

@@ -0,0 +1,286 @@
# Gitea Actions Guide for LLMs
**Purpose**: Guide for LLMs working with Gitea Actions (CI/CD system compatible with GitHub Actions).
**Reference**: [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/)
---
## Overview
**Gitea Actions** is Gitea's CI/CD system that is **compatible with GitHub Actions**. This means:
- Same YAML workflow format
- Same `.github/workflows/` directory structure
- Same triggers and syntax
- Existing GitHub Actions workflows work with minimal or no modifications
- Actions plugins can be downloaded from any Git website
---
## Key Compatibility Points
### 1. Directory Structure
**Same as GitHub**:
```
.github/
└── workflows/
├── workflow1.yml
├── workflow2.yml
└── ...
```
### 2. YAML Format
**Identical to GitHub Actions**:
```yaml
name: Workflow Name
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run command
run: echo "Hello, Gitea Actions!"
```
### 3. Triggers
**Same triggers as GitHub Actions**:
- `push` - On push to repository
- `pull_request` - On pull request events
- `workflow_dispatch` - Manual trigger
- `schedule` - Scheduled runs (cron syntax)
- `repository_dispatch` - External events
### 4. Runners
Gitea Actions uses **Gitea Runners** (similar to GitHub Runners):
- Self-hosted runners
- Can run on various platforms
- Register runners with Gitea instance
- Similar to GitHub Actions runners
---
## Differences from GitHub Actions
### 1. Actions Marketplace
- **GitHub**: Centralized marketplace at github.com/marketplace
- **Gitea**: Actions can be downloaded from any Git website
- **Impact**: Actions plugins can come from GitHub, Gitea, or any Git repository
### 2. Runner Registration
- **GitHub**: Runners managed by GitHub (or self-hosted)
- **Gitea**: All runners are self-hosted
- **Impact**: Must register and manage your own runners
### 3. Some GitHub-Specific Features
- Some GitHub Actions features may not be available
- Check Gitea Actions documentation for specific limitations
- Most common workflows work identically
---
## Creating Workflows
### Basic Workflow Template
```yaml
name: Workflow Name
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
job-name:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Run command
run: |
echo "Running in Gitea Actions"
# Your commands here
```
### Using Actions from Different Sources
**From GitHub**:
```yaml
- uses: actions/checkout@v4
```
**From Gitea**:
```yaml
- uses: gitea.com/owner/action@v1
```
**From Any Git Repository**:
```yaml
- uses: https://git.example.com/owner/action@v1
```
---
## For LLMs: Documentation Guidelines
### When Creating Workflow Documentation
1. **Reference as "Gitea Actions"**:
- "This workflow runs in Gitea Actions"
- "Gitea Actions will execute this workflow on push"
2. **Note Compatibility**:
- "Gitea Actions is compatible with GitHub Actions"
- "This workflow uses the same YAML format as GitHub Actions"
3. **Use Correct Terminology**:
- "Gitea Actions workflows" (not "GitHub Actions workflows")
- "Gitea Runners" (not "GitHub Runners")
- But note: "Same format as GitHub Actions"
### When Creating Workflow Files
1. **Use `.github/workflows/` directory** (same as GitHub)
2. **YAML format is identical** to GitHub Actions
3. **Reference in documentation** as "Gitea Actions workflows"
4. **Note compatibility** when relevant
### Example Documentation
```markdown
## CI/CD Workflows
This repository uses **Gitea Actions** for continuous integration and deployment.
**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/workflows/` directory structure.
### Workflows
- **`kb-lint.yml`** - Validates KB file naming and frontmatter
- **`kb-index-update.yml`** - Auto-updates KB index on push
All workflows are located in `.github/workflows/` and use standard GitHub Actions YAML format.
```
---
## Common Workflow Patterns
### Linting Workflow
```yaml
name: Lint
on:
push:
paths:
- 'src/**/*.rs'
pull_request:
paths:
- 'src/**/*.rs'
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run linter
run: cargo clippy
```
### Testing Workflow
```yaml
name: Test
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run tests
run: cargo test
```
### Index Update Workflow
```yaml
name: Update Index
on:
push:
branches: [ main ]
paths:
- 'kb/**/*.md'
jobs:
update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate index
run: ./kb/scripts/generate-index.sh
- name: Commit changes
run: |
git config user.name "Gitea Actions"
git config user.email "actions@gitea.io"
git add kb/_index.md
git commit -m "chore: update KB index" || exit 0
git push
```
---
## Troubleshooting
### Workflow Not Running
1. **Check runner registration**: Ensure runners are registered with Gitea instance
2. **Check workflow syntax**: Validate YAML syntax
3. **Check triggers**: Verify `on:` conditions match events
4. **Check permissions**: Ensure workflow has necessary permissions
### Actions Not Found
1. **Check action source**: Verify action URL is correct
2. **Check network access**: Ensure runner can access action repository
3. **Use full URL**: For custom actions, use full Git URL
### Runner Issues
1. **Check runner status**: Verify runner is online and connected
2. **Check runner labels**: Ensure `runs-on` matches runner labels
3. **Check runner logs**: Review runner logs for errors
---
## References
- **Gitea Actions Docs**: https://docs.gitea.com/usage/actions/
- **Gitea Runner**: https://docs.gitea.com/usage/actions/runner/
- **Workflow Syntax**: https://docs.gitea.com/usage/actions/usage/
---
**Location**: `docs/GITEA/Gitea-Actions-Guide.md`
**Last Updated**: 2025-01-27