# 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`