Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
db003786f99787fb7f1591e5af8539efa399b059
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

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