Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0a131a296e02b59c0c3efe583ebed53ad52b539d
tendril/docs/AGENT-GUIDELINES.md
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

7.3 KiB
Raw Blame History

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 View Git Blame Copy Permalink