tendril/.cursorrules

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

**Reference**: See `docs/GITEA/Gitea-Actions-Guide.md` for Gitea Actions workflow guidance and compatibility notes.

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
   - Consult `docs/GITEA/Gitea-Actions-Guide.md` for workflow best practices

#### 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
- Consult `docs/GITEA/` documentation for Gitea-specific guidance and platform questions

## Gitea Platform Context

**Repository**: https://git.parkingmeter.info/Mycelium/tendril  
**Platform**: Gitea (self-hosted)  
**Actions System**: Gitea Actions (compatible with GitHub Actions format)

### Gitea Documentation References

When working with Gitea-specific features, workflows, or platform questions:

1. **Consult Gitea Documentation**: See `docs/GITEA/` for comprehensive Gitea guidance
2. **LLM Guidelines**: See `docs/GITEA/LLM-Gitea-Guidelines.md` for LLM-specific guidelines
3. **Actions Guide**: See `docs/GITEA/Gitea-Actions-Guide.md` when working with workflows
4. **API Reference**: See `docs/GITEA/Gitea-API-Reference.md` for API differences
5. **Workflows Guide**: See `docs/GITEA/Gitea-Workflows.md` for common workflows and best practices
6. **Basics Guide**: See `docs/GITEA/Gitea-Basics.md` for core concepts and features

### Platform Terminology

- Use **"Gitea"** (not "GitHub") when referring to the platform
- Use **"Gitea Actions"** (not "GitHub Actions") but note compatibility when relevant
- Use **"Gitea issues"** (not "GitHub issues")
- Use **"Gitea repository"** (not "GitHub repository")
- Use **"Gitea Runners"** (not "GitHub Runners")
- **Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure

## 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
  - Consult `docs/GITEA/Gitea-Actions-Guide.md` for workflow guidance
- 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