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
parent 0a131a296e
commit 03db6efeb8
17 changed files with 892 additions and 16 deletions
--- a/kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md
+++ b/kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md
@@ -0,0 +1,209 @@
+# Phase 1: Phase Documentation System - Detailed Plan
+
+**Objective**: Set up phase-based project management with synchronized documents
+
+**Status**: Ready for Review  
+**Date**: 2025-01-27
+
+---
+
+## Overview
+
+Phase 1 establishes the phase documentation system that will track all project work in synchronized documents. Each phase will have four documents that stay in sync automatically via Cursor rules.
+
+---
+
+## Tasks Breakdown
+
+### Task 1: Create Phase Documentation Templates
+
+**Location**: `tendril/phases/phase-00-foundation/`
+
+**Files to Create**:
+1. **`blueprint.md`** - Complete phase specification template
+2. **`tasks.md`** - Task tracking template (mirrors Gitea issues)
+3. **`decisions.md`** - ADR (Architecture Decision Record) template
+4. **`changelog.md`** - Change history template
+
+**Templates Source**: `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
+
+**Customizations Needed**:
+- Replace `pairs/phases/` with `tendril/phases/`
+- Replace "GitHub issues" with "Gitea issues" in tasks.md
+- Update project name to "Tendril"
+- Update repository URL to Gitea instance
+
+---
+
+### Task 2: Populate Phase 0 (Foundation) with Current Project State
+
+**Location**: `tendril/phases/phase-00-foundation/`
+
+**Data Sources**:
+- `PROJECT_STATUS.md` - Current v0.1.0 status
+- `README.md` - Project description and features
+- `DEVELOPMENT.md` - Architecture and roadmap
+- Phase 0 work just completed (Cursor rules, directory structure, Gitea docs)
+
+**Phase 0 Content to Document**:
+
+**Blueprint.md**:
+- **Project**: Tendril
+- **Phase**: Phase 0: Foundation & Cursor Rules Setup
+- **Status**: ✅ Complete
+- **Objectives**:
+  - Establish Cursor rules system
+  - Create directory structure
+  - Set up agent guidelines
+  - Create Gitea documentation
+  - Organize phase updates documentation
+- **Deliverables**:
+  - `.cursorrules` file
+  - `docs/AGENT-GUIDELINES.md`
+  - `docs/GITEA/` documentation suite
+  - `kb/_guides/PROJECT-SETUP-GUIDE/` organization
+  - Complete directory structure
+- **Timeline**: Completed 2025-01-27
+- **Definition of Done**: All Phase 0 tasks completed and committed
+
+**Tasks.md**:
+- Mirror completed work from Phase 0
+- Mark all Phase 0 tasks as complete
+- Reference commit: `0a131a2`
+
+**Decisions.md**:
+- ADR-000: Use Gitea (self-hosted) instead of GitHub
+- ADR-001: Use `tendril/phases/` directory structure
+- ADR-002: Implement comprehensive Cursor rules system
+- ADR-003: Create Gitea-specific documentation
+
+**Changelog.md**:
+- **2025-01-27**: Phase 0 completed - Established foundation
+  - Created `.cursorrules` with comprehensive rules
+  - Created directory structure (phases, KB, workflows, prompts)
+  - Created `docs/AGENT-GUIDELINES.md`
+  - Created Gitea documentation suite
+  - Organized phase updates documentation
+  - Committed all changes (commit `0a131a2`)
+
+---
+
+### Task 3: Create Phase 1 Blueprint for Next Development Cycle
+
+**Location**: `tendril/phases/phase-01-testing-validation/` (or similar name)
+
+**Phase 1 Content** (based on PROJECT_STATUS.md roadmap):
+
+**Blueprint.md**:
+- **Project**: Tendril
+- **Phase**: Phase 1: Testing & Validation
+- **Status**: ⏳ Planned
+- **Objectives**:
+  - Test with actual Gitea instances (various versions)
+  - Test binary discovery on multiple systems
+  - Test Docker mode on Linux, macOS, Windows
+  - Test with self-hosted Gitea instances
+  - Validate error messages are helpful
+  - Performance testing with large repositories
+- **Deliverables**:
+  - Test results documentation
+  - Platform compatibility matrix
+  - Error message improvements
+  - Performance benchmarks
+- **Timeline**: TBD
+- **Definition of Done**: All testing complete, results documented, issues resolved
+
+**Tasks.md**:
+- Create tasks from PROJECT_STATUS.md "What's Next" section
+- Link to Gitea issues when created
+- Organize by category (Testing, UX, Documentation, Release)
+
+**Decisions.md**:
+- Will be populated as decisions are made during Phase 1
+
+**Changelog.md**:
+- Will be populated as Phase 1 progresses
+
+---
+
+## Customizations for Tendril
+
+### Directory Structure
+- **Use**: `tendril/phases/` (not `pairs/phases/`)
+- **Reason**: Matches project name and structure
+
+### Platform References
+- **Use**: "Gitea" (not "GitHub")
+- **Tasks.md**: "mirrors Gitea issues" (not "GitHub issues")
+- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
+
+### Project Context
+- **Project Name**: Tendril
+- **Current Version**: v0.1.0
+- **Language**: Rust (WASM for Zed extension)
+- **Platform**: Gitea (self-hosted)
+
+---
+
+## Synchronization Rules (Already in .cursorrules)
+
+When `blueprint.md` is modified:
+1. ✅ Update `changelog.md` with today's date and description
+2. ✅ Sync `tasks.md` with blueprint deliverables
+3. ✅ Review `decisions.md` for new ADRs needed
+4. ✅ Verify consistency across all documents
+
+---
+
+## Files to Create
+
+### Phase 0 (Foundation)
+```
+tendril/phases/phase-00-foundation/
+├── blueprint.md      # Phase 0 specification
+├── tasks.md          # Phase 0 tasks (all complete)
+├── decisions.md       # Phase 0 ADRs
+└── changelog.md      # Phase 0 change history
+```
+
+### Phase 1 (Testing & Validation)
+```
+tendril/phases/phase-01-testing-validation/
+├── blueprint.md      # Phase 1 specification
+├── tasks.md          # Phase 1 tasks (from PROJECT_STATUS.md)
+├── decisions.md      # Phase 1 ADRs (empty initially)
+└── changelog.md      # Phase 1 change history (empty initially)
+```
+
+---
+
+## Review Checklist
+
+Before implementing Phase 1, verify:
+
+- [ ] Templates use `tendril/phases/` (not `pairs/phases/`)
+- [ ] All references say "Gitea" (not "GitHub")
+- [ ] Tasks.md says "mirrors Gitea issues"
+- [ ] Project name is "Tendril" throughout
+- [ ] Repository URL is Gitea instance
+- [ ] Phase 0 content accurately reflects completed work
+- [ ] Phase 1 objectives align with PROJECT_STATUS.md roadmap
+- [ ] All dates are in YYYY-MM-DD format
+- [ ] Status indicators are consistent (✅ Complete, 🔄 In Progress, ⏳ Planned)
+
+---
+
+## Next Steps After Phase 1
+
+Once Phase 1 is complete:
+- Phase 2: KB System Setup
+- Phase 3: Gitea Actions Workflows
+- Phase 4: LLM Usage Guides
+- Phase 5: Documentation Migration
+- Phase 6: Validation and Testing
+
+---
+
+**Location**: `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md`  
+**Related**: `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`, `PROJECT_STATUS.md`
+