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.
This commit is contained in:
217
docs/AGENT-GUIDELINES.md
Normal file
217
docs/AGENT-GUIDELINES.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# Agent Guidelines for Tendril
|
||||
|
||||
**Purpose**: This document provides guidelines for AI agents (like Cursor AI) working on the Tendril project. It defines the project structure, documentation standards, and workflow expectations.
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Tendril** is a Zed IDE extension that integrates with Gitea through the Model Context Protocol (MCP). It provides seamless access to Gitea repositories, issues, pull requests, and more directly within the Zed editor.
|
||||
|
||||
**Repository**: https://git.parkingmeter.info/Mycelium/tendril
|
||||
**Current Version**: v0.1.0
|
||||
**Language**: Rust (compiled to WASM for Zed extension)
|
||||
**License**: Apache 2.0
|
||||
|
||||
---
|
||||
|
||||
## Documentation System Architecture
|
||||
|
||||
Tendril uses a comprehensive documentation system with the following components:
|
||||
|
||||
### Phase Documentation System
|
||||
|
||||
**Location**: `tendril/phases/phase-XX-name/`
|
||||
|
||||
Each phase has four synchronized documents:
|
||||
- **`blueprint.md`** - Complete phase specification
|
||||
- **`tasks.md`** - Task tracking (mirrors Gitea issues)
|
||||
- **`decisions.md`** - Architecture Decision Records (ADRs)
|
||||
- **`changelog.md`** - Change history
|
||||
|
||||
**Critical Rule**: When `blueprint.md` is modified, ALL related documents must be checked and updated in the same session.
|
||||
|
||||
### Knowledge Base (KB) System
|
||||
|
||||
**Location**: `kb/`
|
||||
|
||||
The KB system provides a lightweight, LLM-friendly staging area for external information:
|
||||
- `kb/01_projects/tendril/` - Project-specific notes
|
||||
- `kb/02_systems/` - Infrastructure/tooling
|
||||
- `kb/03_research/` - Informal research
|
||||
- `kb/04_design/` - Product specs/UX
|
||||
- `kb/05_decisions/` - Project-level ADRs
|
||||
- `kb/06_glossary/` - Terms/acronyms
|
||||
- `kb/07_playbooks/` - How-to guides
|
||||
- `kb/08_archive/` - Superseded content
|
||||
|
||||
**KB File Naming**: `YYYY-MM-DD--slug--type.md`
|
||||
**KB Frontmatter**: All KB files require complete YAML frontmatter with 18 required fields.
|
||||
|
||||
### Gitea Automation
|
||||
|
||||
**Location**: `.github/`
|
||||
|
||||
- `.github/workflows/` - Gitea Actions workflows (compatible with GitHub Actions format)
|
||||
- `.github/README.md` - Automation overview
|
||||
- `.github/CHANGELOG.md` - Workflow change tracking
|
||||
- `.github/decisions.md` - Automation decisions
|
||||
|
||||
**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure.
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Documentation is the Single Source of Truth** - Always read phase blueprints before making changes
|
||||
2. **Synchronization is Mandatory** - Related documents must stay in sync automatically
|
||||
3. **LLM-Friendly Structure** - All documentation is structured for AI agent consumption
|
||||
4. **Incremental Updates** - Update documentation as you work, not at the end
|
||||
5. **Validation at Every Step** - Automated validation ensures consistency
|
||||
|
||||
---
|
||||
|
||||
## Mandatory Workflows
|
||||
|
||||
### When Editing Phase Blueprints
|
||||
|
||||
1. **Read related documents first**:
|
||||
- `changelog.md` - Check recent changes
|
||||
- `tasks.md` - Understand current task status
|
||||
- `decisions.md` - Review existing ADRs
|
||||
|
||||
2. **After editing `blueprint.md`**:
|
||||
- Update `changelog.md` with today's date and description
|
||||
- Sync `tasks.md` with blueprint deliverables and definition of done
|
||||
- Review `decisions.md` for new ADRs needed
|
||||
- Verify project name consistency across all documents
|
||||
|
||||
3. **Before completing**:
|
||||
- Provide summary of all files modified
|
||||
- Ask user if they want to push changes
|
||||
|
||||
### When Creating KB Files
|
||||
|
||||
1. **Before creating**:
|
||||
- Check `kb/_index.md` for existing related content
|
||||
- Determine appropriate category using routing decision tree
|
||||
- Assess routing confidence (0.00-1.00)
|
||||
|
||||
2. **After creating**:
|
||||
- Run `kb/scripts/generate-index.sh` to update index
|
||||
- Update `kb/CHANGELOG.md` with entry
|
||||
- Commit all three changes together
|
||||
|
||||
### When Modifying Gitea Actions Workflows
|
||||
|
||||
1. **Update `.github/CHANGELOG.md`** - Document what changed
|
||||
2. **Update `.github/decisions.md`** - Document decision rationale (if applicable)
|
||||
3. **Update `.github/README.md`** - Update workflow descriptions (if needed)
|
||||
|
||||
**Note**: Gitea Actions workflows use the same YAML format as GitHub Actions, so existing GitHub Actions workflows can be used with minimal or no modifications.
|
||||
|
||||
### When Completing Work Sessions
|
||||
|
||||
1. **Check README.md**:
|
||||
- Verify phase statuses are accurate
|
||||
- Update if phase statuses changed
|
||||
- Verify links are correct
|
||||
|
||||
2. **Verify consistency**:
|
||||
- Project name matches across documents
|
||||
- Dates are consistent
|
||||
- Status indicators are aligned
|
||||
|
||||
---
|
||||
|
||||
## File Structure Conventions
|
||||
|
||||
### Directory Naming
|
||||
- **Phase directories**: `phase-XX-name` where XX is zero-padded (00, 01, 02, etc.)
|
||||
- **KB categories**: `01_projects/`, `02_systems/`, etc. (numbered for ordering)
|
||||
- **Special KB directories**: `_guides/`, `_templates/`, `_inbox/`, `_review_queue/` (underscore prefix)
|
||||
|
||||
### File Naming
|
||||
- **Phase documentation**: `blueprint.md`, `tasks.md`, `decisions.md`, `changelog.md`
|
||||
- **KB files**: `YYYY-MM-DD--slug--type.md`
|
||||
- **Workflows**: `kebab-case.yml`
|
||||
|
||||
### Commit Messages
|
||||
|
||||
**Format**: `type(scope): description`
|
||||
|
||||
**Types**:
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `chore`: Maintenance tasks
|
||||
- `ci`: CI/CD changes
|
||||
|
||||
**Examples**:
|
||||
- `feat(phase-01): Add Zapier integration`
|
||||
- `fix(phase-02): Resolve web link capture (#123)`
|
||||
- `docs(kb): add api-auth-decision and update index/changelog`
|
||||
|
||||
---
|
||||
|
||||
## Critical Rules
|
||||
|
||||
### NEVER Do These Things
|
||||
|
||||
- ❌ **NEVER delete files or folders when committing or pushing**
|
||||
- ❌ NEVER edit blueprint.md without checking related documents
|
||||
- ❌ NEVER leave related documents out of sync
|
||||
- ❌ NEVER assume related documents are already updated
|
||||
- ❌ NEVER skip KB index/changelog updates
|
||||
- ❌ NEVER complete work without checking README.md
|
||||
|
||||
### ALWAYS Do These Things
|
||||
|
||||
- ✅ ALWAYS read related documents before making changes
|
||||
- ✅ ALWAYS update related documents in the same session
|
||||
- ✅ ALWAYS verify consistency across all phase documents
|
||||
- ✅ ALWAYS run KB index generation after KB file changes
|
||||
- ✅ ALWAYS check README.md after significant changes
|
||||
- ✅ ALWAYS provide summaries of what was updated
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Context
|
||||
|
||||
### Technology Stack
|
||||
- **Language**: Rust
|
||||
- **Target**: WASM (WebAssembly) for Zed extension
|
||||
- **Dependencies**: zed_extension_api, serde, schemars
|
||||
- **Build**: `cargo build --target wasm32-unknown-unknown --release`
|
||||
|
||||
### Key Files
|
||||
- `src/mcp_server_gitea.rs` - Main extension logic
|
||||
- `extension.toml` - Zed extension manifest
|
||||
- `Cargo.toml` - Rust project configuration
|
||||
- `configuration/default_settings.jsonc` - Configuration template
|
||||
|
||||
### Current Status
|
||||
- **Version**: v0.1.0
|
||||
- **Status**: Feature-complete for core functionality
|
||||
- **Features**: Binary path resolution, Docker support, cross-platform detection
|
||||
- **Limitations**: SSE mode not supported (Zed API limitation)
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you're unsure about:
|
||||
- **Documentation structure**: See `docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
|
||||
- **KB system**: See `kb/README.md` and `kb/_guides/`
|
||||
- **Phase documentation**: See `tendril/phases/phase-00-foundation/` for examples
|
||||
- **Gitea automation**: See `.github/README.md` and `.github/LLM-Usage-Guide--tendril.md`
|
||||
- **Gitea platform**: See `docs/GITEA/` for comprehensive Gitea documentation
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/AGENT-GUIDELINES.md`
|
||||
**Maintained by**: Tendril Project Maintainers
|
||||
**Based on**: `docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
|
||||
|
||||
Reference in New Issue
Block a user