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
parent 7e49d8c8d4
commit 0a131a296e
11 changed files with 4399 additions and 0 deletions
--- a/.cursorrules
+++ b/.cursorrules
@@ -0,0 +1,278 @@
+# Cursor Rules for Tendril
+
+## Phase Documentation Synchronization Rules
+
+### MANDATORY: When blueprint.md is modified, automatically update related phase documents
+
+When ANY file matching `tendril/phases/phase-*/blueprint.md` is edited or updated:
+
+1. **ALWAYS check and update `changelog.md`** in the same phase directory:
+   - Add a new entry with today's date (YYYY-MM-DD format)
+   - Describe what changed in the blueprint
+   - Use format: `- **YYYY-MM-DD:** [Description of change]`
+
+2. **ALWAYS check and update `tasks.md`** in the same phase directory:
+   - Sync task checkboxes with "Definition of Done" items from blueprint
+   - Sync task list with "Phase Deliverables" section from blueprint
+   - Ensure task status aligns with milestone statuses in blueprint
+   - Update phase status if blueprint status changed
+
+3. **ALWAYS check `decisions.md`** in the same phase directory:
+   - If blueprint changes reflect new architectural decisions, add ADR entry
+   - If decisions are mentioned in blueprint but not in decisions.md, add them
+   - Review that existing ADRs still align with blueprint specifications
+
+4. **ALWAYS verify consistency**:
+   - Project name matches across all phase documents
+   - Dates are consistent (or marked as TBD consistently)
+   - Team roles match where applicable
+   - Status indicators are aligned
+
+#### When Gitea Actions workflows (`.github/workflows/*.yml`) are modified:
+
+1. **ALWAYS update `.github/CHANGELOG.md`**:
+   - Document workflow changes, new triggers, or automation updates
+   - Note any changes to scheduled times or conditions
+   - Include affected workflow name and file path
+
+2. **ALWAYS update `.github/decisions.md`** (if decision-related):
+   - Document the decision behind the workflow change
+   - Explain rationale and alternatives considered
+   - Note impact on automation
+
+3. **ALWAYS update `.github/README.md`** (if structure or behavior changed):
+   - Update workflow descriptions if behavior changed significantly
+   - Add new workflows to overview section
+   - Remove references to deleted workflows
+
+4. **ALWAYS verify workflow references**:
+   - Check that documentation references to workflows use correct file names
+   - Ensure workflow descriptions in docs match actual workflow logic
+
+#### When `.github/` folder is modified (any file):
+
+1. **ALWAYS update `.github/CHANGELOG.md`**:
+   - Document all changes to .github folder structure
+   - Include file paths and what changed
+   - Note if workflows, documentation, or structure was modified
+
+2. **ALWAYS update `.github/decisions.md`** (if decision-related):
+   - Document decisions about .github folder structure
+   - Explain rationale for documentation organization
+   - Note impact on workflow maintenance
+
+3. **ALWAYS update `.github/README.md`** (if structure or purpose changed):
+   - Update overview if folder structure changed
+   - Update workflow descriptions if documentation changed
+   - Ensure all workflows are listed in overview
+
+### Specific Blueprint Change Triggers
+
+When blueprint.md changes include:
+- **Project name change** → Update all phase documents to reflect new name
+- **Milestone status changes** → Update tasks.md and changelog.md
+- **Deliverables completion** → Update tasks.md checkboxes and changelog.md
+- **Team role assignments** → Update changelog.md if significant
+- **Timeline changes** → Update changelog.md with reason
+- **Scope changes** → Update decisions.md if architectural decision involved
+- **Status changes** → Update tasks.md status line
+
+### Workflow for Blueprint Updates
+
+1. After editing blueprint.md, immediately:
+   - Read changelog.md, tasks.md, and decisions.md from the same phase directory
+   - Compare blueprint content with related documents
+   - Identify discrepancies or missing updates
+   - Update all related documents to maintain consistency
+   - Verify no information is lost (only added or synchronized)
+
+2. Before completing any blueprint edit session:
+   - Confirm all related documents have been checked
+   - Confirm all necessary updates have been made
+   - **ALWAYS provide a summary** of what was updated:
+     * List each file that was modified
+     * Describe what changes were made to each file
+     * Note any files that were checked but didn't need updates
+   - **ALWAYS ask the user** if they want to push these changes to the remote repository
+
+### Never Skip These Steps
+
+- ❌ **NEVER delete files or folders when committing or pushing to the repository**
+- ❌ NEVER edit blueprint.md without checking related documents
+- ❌ NEVER leave related documents out of sync
+- ❌ NEVER assume related documents are already updated
+- ✅ ALWAYS read related documents before making changes
+- ✅ ALWAYS update related documents in the same session
+- ✅ ALWAYS verify consistency across all phase documents
+
+## General Project Rules
+
+- Always read phase blueprints before making changes
+- **CRITICAL: NEVER delete files or folders when committing or pushing**
+  - **UNDER NO CIRCUMSTANCES** are you to delete files or folders whenever the user requests for you to commit from the local repo or push to the remote repo
+  - Commits and pushes should only include file modifications, additions, and updates
+  - If file deletion is needed, it must be explicitly requested by the user in a separate, clear request
+  - Never perform cleanup, organization, or deletion operations as part of commit/push workflows
+- Update documentation incrementally, not at the end
+- Follow the structure defined in `docs/AGENT-GUIDELINES.md`
+- Use conventional commit messages with phase references
+
+## KB Ingestion & Routing Rules
+
+### MANDATORY: KB Ingestion System Behavior
+
+When the chat starts with the text "SYSTEM — KB Ingestion & Routing" (from `/kb/_guides/KB_INGEST_PROMPT.md`), treat it as a system message and follow KB ingestion protocols.
+
+### KB Write Scope & Constraints
+
+**Assistant Rules:**
+- Only create or update files under `/kb` except when explicitly asked otherwise
+- Never modify files in `/kb/_guides` or `/kb/_templates`
+- Enforce the filename pattern: `^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)\.md$`
+- Before writing KB files, ensure YAML frontmatter contains all required keys: `title`, `date`, `captured_at`, `author`, `source`, `source_type`, `project`, `related_projects`, `topics`, `tags`, `type`, `status`, `phase_relevance`, `routing_hint`, `proposed_path`, `routing_confidence`, `related`, `summary`
+- Include project-specific fields: `captured_at` (same as date), `source_type` (voice|web|pdf|image|personal_note|chat|pulse), `related_projects` (same as project), `phase_relevance[]` (array of phase-XX or empty)
+- Optional fields: `key_takeaways[]`, `action_candidates[]`
+- If the user pastes multiple unrelated chunks, split into separate files (max 5) and suffix with `--p1`, `--p2`, etc.
+- If routing is ambiguous, write to `/kb/_inbox` and include `routing_hint` explaining uncertainty
+- Respond with a single JSON code block as specified by the KB ingestion system prompt
+- Default `author` is `["unknown author"]` if not specified
+- Default `project` is `["tendril"]` for Tendril project
+
+**User Guidelines:**
+- Provide raw content after the system prompt
+- Avoid mixing unrelated topics when possible
+- Paste `/kb/_guides/KB_INGEST_PROMPT.md` contents as the first message in a Cursor chat before pasting any material
+
+### KB System vs Research System
+
+**When to use KB system (`/kb/`):**
+- Pulse Daily chats and ideas
+- Informal notes and thoughts about the project
+- External information that may inform the project
+- Project-level decisions (complements phase-specific ADRs)
+- How-to guides and playbooks
+- Glossary entries
+- Design ideas and UX concepts
+
+**When to use Research system (`tendril/research/notes/` or equivalent):**
+- Formal research articles, papers, and web content
+- Content that will be actively researched and indexed
+- Research materials that go through ingestion pipeline
+- Content requiring full research metadata schema
+
+**Integration:**
+- KB entries can reference project phases via `phase_relevance[]` field
+- KB decisions complement (not replace) phase-specific ADRs
+- KB entries use aligned metadata schema for compatibility
+
+### KB Workflow Maintenance
+
+**When KB structure or guidelines change:**
+- Check and update Gitea Actions workflows (`.github/workflows/kb-lint.yml`) if KB validation rules change
+- Check and update README.md if KB system is added or significantly modified
+- Ensure workflows stay in sync with KB guidelines in `/kb/_guides/`
+
+### KB Index Check Requirements
+
+**MANDATORY: Pre-Planning KB Check**
+
+Before starting any planning or development work, ALWAYS:
+
+1. **Read `kb/README.md`** to understand the KB system (if first time working with KB)
+2. **Read `kb/_index.md`** to check for relevant KB content
+3. **Search `kb/_index.md`** for keywords related to current task:
+   - Check topics index for relevant topics
+   - Check tags index for relevant tags
+   - Search file titles and summaries
+   - Check relevant categories (e.g., decisions, specs, research)
+   - Check phase relevance index for content related to current phase
+4. **If relevant KB content found:**
+   - List specific KB files that might be relevant (with paths from index)
+   - Summarize relevant entries from index (title, summary, topics, tags, phase relevance)
+   - Ask user if they want to incorporate KB knowledge into current work
+   - If user confirms, read the actual KB files referenced in index
+   - Reference KB files in documentation or code comments when appropriate
+
+**KB Index and Changelog Update Requirement**
+
+**MANDATORY:** After creating, modifying, or deleting ANY file in `kb/` (except `_guides/`, `_templates/`, `README.md`, `_index.md`, and `CHANGELOG.md`):
+
+1. **Run index generation script:**
+   ```bash
+   kb/scripts/generate-index.sh
+   ```
+   - This regenerates `kb/_index.md` with current KB content
+   - Verify the script completes successfully
+   - Check that changes appear in `kb/_index.md`
+
+2. **Update KB changelog:**
+   - Add entry to `kb/CHANGELOG.md` with date-based format:
+     ```markdown
+     ## [YYYY-MM-DD] KB File Added/Modified/Deleted
+     
+     ### Added/Changed/Removed
+     - `kb/XX_category/filename.md` - [Brief description]
+     ```
+   - Use today's date (YYYY-MM-DD format)
+   - Include the full file path relative to repository root
+   - Provide a brief description (1-2 sentences) of what changed
+
+3. **Commit all changes together:**
+   - Commit KB file change, index update, and changelog entry together
+   - Use commit message: `docs(kb): [action] [filename-slug] and update index/changelog`
+   - Examples:
+     - `docs(kb): add api-auth-decision and update index/changelog`
+     - `docs(kb): update cursor-workflow and update index/changelog`
+     - `docs(kb): remove obsolete-note and update index/changelog`
+
+4. **Note:** Gitea Actions will auto-update index on push to main, but local updates should also regenerate index. Changelog updates are always manual and must be done locally.
+
+**NEVER skip these steps** - Both index and changelog updates are mandatory for KB system integrity.
+
+## README Maintenance Rules
+
+### MANDATORY: Check and Update README After Work Completion
+
+**After completing ANY work session that involves:**
+- Phase blueprint updates
+- Phase status changes
+- New deliverables or features
+- Directory structure changes
+- Project name or description changes
+- Major architectural decisions
+
+**You MUST:**
+
+1. **Read the current README.md** to understand its current state
+
+2. **Check if updates are needed** by verifying:
+   - Phase statuses are accurate (✅ Complete, 🔄 In Progress, ⏳ Planned)
+   - Phase names match current blueprints
+   - Directory structure reflects actual project layout
+   - Links to phase blueprints are correct
+   - Project description matches current state
+   - Getting Started section is accurate
+
+3. **Update README.md if any of the following changed:**
+   - Phase status (e.g., Phase 1 moved from Planned to In Progress)
+   - Phase names or descriptions
+   - Project structure (new directories, renamed files)
+   - Project name or branding
+   - Key features or capabilities
+   - Documentation links or paths
+
+4. **Before completing work session:**
+   - Confirm README.md has been checked
+   - Update README.md if needed
+   - Verify all links in README.md are valid
+   - Ensure README.md accurately reflects current project state
+
+### Never Skip README Updates
+
+- ❌ NEVER complete work without checking README.md
+- ❌ NEVER leave README.md out of sync with project state
+- ❌ NEVER assume README.md is already up to date
+- ✅ ALWAYS check README.md after making significant changes
+- ✅ ALWAYS update README.md when phase statuses change
+- ✅ ALWAYS verify README.md accuracy before committing
+