Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
72d74f86adfca22be031c276e8328abd9f5f63e8
tendril/docs/AGENT-GUIDELINES.md
Data Warrior 03db6efeb8 docs: reorganize project structure and add Gitea platform context 
This commit implements a comprehensive reorganization of project documentation
and adds explicit Gitea platform context throughout the project.

## Documentation Reorganization

### File Moves (Content Preserved)
- Moved CURSOR_WINDOWS_SETUP.md to kb/_guides/ for better organization
- Moved docs/PHASE-UPDATES/ to kb/_guides/PROJECT-SETUP-GUIDE/:
  - COMPLETE-SYSTEM-REPLICATION-GUIDE.md
  - PHASE-0-GITEA-UPDATES.md
  - README.md
- Added new file: kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md

**Reason**: Consolidate project setup and configuration guides into the
knowledge base structure for better discoverability and organization.

### New Phase Documentation Structure
Created tendril/phases/ directory with structured phase documentation:
- phase-00-foundation/: blueprint, changelog, decisions, tasks
- phase-01-testing-validation/: blueprint, changelog, decisions, tasks

**Reason**: Establish consistent phase documentation structure following
project guidelines for phase management and tracking.

## Gitea Platform Context Integration

### .cursorrules Updates
- Added comprehensive Gitea platform context section
- Added Gitea documentation references for workflows and platform questions
- Added platform terminology guidelines (Gitea vs GitHub)
- Added references to docs/GITEA/ documentation throughout rules

**Reason**: Ensure all AI agents and contributors use correct Gitea terminology
and have clear guidance on where to find Gitea-specific documentation.

### Documentation Path Updates
- CONTRIBUTING.md: Updated CURSOR_WINDOWS_SETUP.md path reference
- docs/AGENT-GUIDELINES.md: Updated path references to moved documentation
- PROJECT_STATUS.md: Updated comment to mention Gitea Actions

**Reason**: Maintain link integrity after file reorganization and ensure
documentation references point to correct locations.

## Impact and Benefits

1. **Better Organization**: Documentation is now organized in logical
   structures (kb/ for knowledge base, tendril/phases/ for phase docs)

2. **Clear Platform Context**: Explicit Gitea platform references prevent
   confusion with GitHub terminology and provide clear documentation paths

3. **Consistent Structure**: Phase documentation follows standardized format
   (blueprint, changelog, decisions, tasks) for easier maintenance

4. **Improved Discoverability**: Guides consolidated in kb/_guides/ make it
   easier to find setup and configuration information

All file moves preserve content - no information was lost in this reorganization.
2025-11-11 11:38:44 -07:00

218 lines
7.3 KiB
Markdown
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 `kb/_guides/PROJECT-SETUP-GUIDE/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**: `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
Reference in New Issue View Git Blame Copy Permalink