From 0a131a296e02b59c0c3efe583ebed53ad52b539d Mon Sep 17 00:00:00 2001 From: Data Warrior Date: Tue, 11 Nov 2025 11:09:36 -0700 Subject: [PATCH] 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. --- .cursorrules | 278 ++ docs/AGENT-GUIDELINES.md | 217 ++ docs/GITEA/Gitea-API-Reference.md | 243 ++ docs/GITEA/Gitea-Actions-Guide.md | 286 ++ docs/GITEA/Gitea-Basics.md | 213 ++ docs/GITEA/Gitea-Workflows.md | 278 ++ docs/GITEA/LLM-Gitea-Guidelines.md | 220 ++ docs/GITEA/README.md | 106 + .../COMPLETE-SYSTEM-REPLICATION-GUIDE.md | 2437 +++++++++++++++++ docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md | 62 + docs/PHASE-UPDATES/README.md | 59 + 11 files changed, 4399 insertions(+) create mode 100644 .cursorrules create mode 100644 docs/AGENT-GUIDELINES.md create mode 100644 docs/GITEA/Gitea-API-Reference.md create mode 100644 docs/GITEA/Gitea-Actions-Guide.md create mode 100644 docs/GITEA/Gitea-Basics.md create mode 100644 docs/GITEA/Gitea-Workflows.md create mode 100644 docs/GITEA/LLM-Gitea-Guidelines.md create mode 100644 docs/GITEA/README.md create mode 100644 docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md create mode 100644 docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md create mode 100644 docs/PHASE-UPDATES/README.md diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000..be0cfa2 --- /dev/null +++ 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 + diff --git a/docs/AGENT-GUIDELINES.md b/docs/AGENT-GUIDELINES.md new file mode 100644 index 0000000..b75d325 --- /dev/null +++ b/docs/AGENT-GUIDELINES.md @@ -0,0 +1,217 @@ +# 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 `docs/PHASE-UPDATES/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**: `docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md` + diff --git a/docs/GITEA/Gitea-API-Reference.md b/docs/GITEA/Gitea-API-Reference.md new file mode 100644 index 0000000..a4d5488 --- /dev/null +++ b/docs/GITEA/Gitea-API-Reference.md @@ -0,0 +1,243 @@ +# Gitea API Reference for LLMs + +**Purpose**: API differences and considerations when working with Gitea programmatically. + +**Reference**: [Gitea API Documentation](https://docs.gitea.com/api/) + +--- + +## Overview + +Gitea provides a REST API that is **similar to GitHub's API** but not identical. The API allows programmatic access to repositories, issues, pull requests, and more. + +**Base URL**: `https://your-gitea-instance.com/api/v1` + +--- + +## Authentication + +### Personal Access Token + +**Creating a token**: +1. Log in to Gitea +2. Go to Settings → Applications → Generate New Token +3. Set name and permissions +4. Copy token + +**Using token**: +```bash +curl -H "Authorization: token YOUR_TOKEN" \ + https://git.parkingmeter.info/api/v1/user +``` + +**In code**: +```rust +let client = reqwest::Client::new(); +let response = client + .get("https://git.parkingmeter.info/api/v1/user") + .header("Authorization", format!("token {}", token)) + .send() + .await?; +``` + +--- + +## Common Endpoints + +### User Information + +**Get authenticated user**: +``` +GET /api/v1/user +``` + +**Get user by username**: +``` +GET /api/v1/users/{username} +``` + +### Repositories + +**List repositories**: +``` +GET /api/v1/user/repos +GET /api/v1/users/{username}/repos +GET /api/v1/orgs/{org}/repos +``` + +**Get repository**: +``` +GET /api/v1/repos/{owner}/{repo} +``` + +**Create repository**: +``` +POST /api/v1/user/repos +``` + +### Issues + +**List issues**: +``` +GET /api/v1/repos/{owner}/{repo}/issues +``` + +**Get issue**: +``` +GET /api/v1/repos/{owner}/{repo}/issues/{index} +``` + +**Create issue**: +``` +POST /api/v1/repos/{owner}/{repo}/issues +``` + +### Pull Requests + +**List pull requests**: +``` +GET /api/v1/repos/{owner}/{repo}/pulls +``` + +**Get pull request**: +``` +GET /api/v1/repos/{owner}/{repo}/pulls/{index} +``` + +**Create pull request**: +``` +POST /api/v1/repos/{owner}/{repo}/pulls +``` + +--- + +## Differences from GitHub API + +### 1. Base URL + +- **GitHub**: `https://api.github.com` +- **Gitea**: `https://your-instance.com/api/v1` + +### 2. Issue/PR Numbers + +- **GitHub**: Uses sequential numbers across repository +- **Gitea**: Uses index (similar, but may differ in some cases) + +### 3. Some Endpoints + +- Gitea may have different endpoints for some operations +- Check Gitea API documentation for specific endpoints +- Most common operations are similar + +### 4. Webhooks + +- Gitea webhooks are compatible with GitHub format +- Same payload structure +- Same event types (push, pull_request, etc.) + +--- + +## For LLMs: API Usage Guidelines + +### When Documenting API Usage + +**Reference Gitea API**: +```markdown +## API Integration + +This project uses the **Gitea API** for programmatic access. + +**Base URL**: `https://git.parkingmeter.info/api/v1` + +**Authentication**: Personal Access Token + +**Example**: +```bash +curl -H "Authorization: token YOUR_TOKEN" \ + https://git.parkingmeter.info/api/v1/user/repos +``` +``` + +### When Creating API Clients + +**Use Gitea base URL**: +```rust +const GITEA_BASE_URL: &str = "https://git.parkingmeter.info/api/v1"; +``` + +**Use Gitea authentication**: +```rust +let client = reqwest::Client::new(); +let response = client + .get(&format!("{}/user", GITEA_BASE_URL)) + .header("Authorization", format!("token {}", token)) + .send() + .await?; +``` + +### When Referencing Documentation + +**Link to Gitea API docs**: +```markdown +For complete API documentation, see: +https://docs.gitea.com/api/ +``` + +--- + +## Common Use Cases + +### 1. Listing Repositories + +```bash +curl -H "Authorization: token YOUR_TOKEN" \ + https://git.parkingmeter.info/api/v1/user/repos +``` + +### 2. Creating an Issue + +```bash +curl -X POST \ + -H "Authorization: token YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"title":"New Issue","body":"Issue description"}' \ + https://git.parkingmeter.info/api/v1/repos/owner/repo/issues +``` + +### 3. Creating a Pull Request + +```bash +curl -X POST \ + -H "Authorization: token YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"title":"PR Title","head":"feature-branch","base":"main"}' \ + https://git.parkingmeter.info/api/v1/repos/owner/repo/pulls +``` + +--- + +## MCP Server Integration + +**Tendril** uses the Gitea MCP server for integration with Zed IDE. The MCP server provides: + +- Repository management +- Issue management +- Pull request management +- File operations +- And more + +**Reference**: See `src/mcp_server_gitea.rs` for implementation details. + +--- + +## References + +- **Gitea API Docs**: https://docs.gitea.com/api/ +- **API Overview**: https://docs.gitea.com/api/overview/ +- **Authentication**: https://docs.gitea.com/api/authentication/ + +--- + +**Location**: `docs/GITEA/Gitea-API-Reference.md` +**Last Updated**: 2025-01-27 + diff --git a/docs/GITEA/Gitea-Actions-Guide.md b/docs/GITEA/Gitea-Actions-Guide.md new file mode 100644 index 0000000..361c4a2 --- /dev/null +++ b/docs/GITEA/Gitea-Actions-Guide.md @@ -0,0 +1,286 @@ +# Gitea Actions Guide for LLMs + +**Purpose**: Guide for LLMs working with Gitea Actions (CI/CD system compatible with GitHub Actions). + +**Reference**: [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/) + +--- + +## Overview + +**Gitea Actions** is Gitea's CI/CD system that is **compatible with GitHub Actions**. This means: + +- Same YAML workflow format +- Same `.github/workflows/` directory structure +- Same triggers and syntax +- Existing GitHub Actions workflows work with minimal or no modifications +- Actions plugins can be downloaded from any Git website + +--- + +## Key Compatibility Points + +### 1. Directory Structure + +**Same as GitHub**: +``` +.github/ +└── workflows/ + ├── workflow1.yml + ├── workflow2.yml + └── ... +``` + +### 2. YAML Format + +**Identical to GitHub Actions**: +```yaml +name: Workflow Name + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run command + run: echo "Hello, Gitea Actions!" +``` + +### 3. Triggers + +**Same triggers as GitHub Actions**: +- `push` - On push to repository +- `pull_request` - On pull request events +- `workflow_dispatch` - Manual trigger +- `schedule` - Scheduled runs (cron syntax) +- `repository_dispatch` - External events + +### 4. Runners + +Gitea Actions uses **Gitea Runners** (similar to GitHub Runners): +- Self-hosted runners +- Can run on various platforms +- Register runners with Gitea instance +- Similar to GitHub Actions runners + +--- + +## Differences from GitHub Actions + +### 1. Actions Marketplace + +- **GitHub**: Centralized marketplace at github.com/marketplace +- **Gitea**: Actions can be downloaded from any Git website +- **Impact**: Actions plugins can come from GitHub, Gitea, or any Git repository + +### 2. Runner Registration + +- **GitHub**: Runners managed by GitHub (or self-hosted) +- **Gitea**: All runners are self-hosted +- **Impact**: Must register and manage your own runners + +### 3. Some GitHub-Specific Features + +- Some GitHub Actions features may not be available +- Check Gitea Actions documentation for specific limitations +- Most common workflows work identically + +--- + +## Creating Workflows + +### Basic Workflow Template + +```yaml +name: Workflow Name + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + job-name: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run command + run: | + echo "Running in Gitea Actions" + # Your commands here +``` + +### Using Actions from Different Sources + +**From GitHub**: +```yaml +- uses: actions/checkout@v4 +``` + +**From Gitea**: +```yaml +- uses: gitea.com/owner/action@v1 +``` + +**From Any Git Repository**: +```yaml +- uses: https://git.example.com/owner/action@v1 +``` + +--- + +## For LLMs: Documentation Guidelines + +### When Creating Workflow Documentation + +1. **Reference as "Gitea Actions"**: + - "This workflow runs in Gitea Actions" + - "Gitea Actions will execute this workflow on push" + +2. **Note Compatibility**: + - "Gitea Actions is compatible with GitHub Actions" + - "This workflow uses the same YAML format as GitHub Actions" + +3. **Use Correct Terminology**: + - "Gitea Actions workflows" (not "GitHub Actions workflows") + - "Gitea Runners" (not "GitHub Runners") + - But note: "Same format as GitHub Actions" + +### When Creating Workflow Files + +1. **Use `.github/workflows/` directory** (same as GitHub) +2. **YAML format is identical** to GitHub Actions +3. **Reference in documentation** as "Gitea Actions workflows" +4. **Note compatibility** when relevant + +### Example Documentation + +```markdown +## CI/CD Workflows + +This repository uses **Gitea Actions** for continuous integration and deployment. + +**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/workflows/` directory structure. + +### Workflows + +- **`kb-lint.yml`** - Validates KB file naming and frontmatter +- **`kb-index-update.yml`** - Auto-updates KB index on push + +All workflows are located in `.github/workflows/` and use standard GitHub Actions YAML format. +``` + +--- + +## Common Workflow Patterns + +### Linting Workflow + +```yaml +name: Lint + +on: + push: + paths: + - 'src/**/*.rs' + pull_request: + paths: + - 'src/**/*.rs' + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run linter + run: cargo clippy +``` + +### Testing Workflow + +```yaml +name: Test + +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run tests + run: cargo test +``` + +### Index Update Workflow + +```yaml +name: Update Index + +on: + push: + branches: [ main ] + paths: + - 'kb/**/*.md' + +jobs: + update: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Generate index + run: ./kb/scripts/generate-index.sh + - name: Commit changes + run: | + git config user.name "Gitea Actions" + git config user.email "actions@gitea.io" + git add kb/_index.md + git commit -m "chore: update KB index" || exit 0 + git push +``` + +--- + +## Troubleshooting + +### Workflow Not Running + +1. **Check runner registration**: Ensure runners are registered with Gitea instance +2. **Check workflow syntax**: Validate YAML syntax +3. **Check triggers**: Verify `on:` conditions match events +4. **Check permissions**: Ensure workflow has necessary permissions + +### Actions Not Found + +1. **Check action source**: Verify action URL is correct +2. **Check network access**: Ensure runner can access action repository +3. **Use full URL**: For custom actions, use full Git URL + +### Runner Issues + +1. **Check runner status**: Verify runner is online and connected +2. **Check runner labels**: Ensure `runs-on` matches runner labels +3. **Check runner logs**: Review runner logs for errors + +--- + +## References + +- **Gitea Actions Docs**: https://docs.gitea.com/usage/actions/ +- **Gitea Runner**: https://docs.gitea.com/usage/actions/runner/ +- **Workflow Syntax**: https://docs.gitea.com/usage/actions/usage/ + +--- + +**Location**: `docs/GITEA/Gitea-Actions-Guide.md` +**Last Updated**: 2025-01-27 + diff --git a/docs/GITEA/Gitea-Basics.md b/docs/GITEA/Gitea-Basics.md new file mode 100644 index 0000000..f7d7008 --- /dev/null +++ b/docs/GITEA/Gitea-Basics.md @@ -0,0 +1,213 @@ +# Gitea Basics for LLMs + +**Purpose**: Core concepts and features of Gitea that LLMs should understand when working with Gitea-based projects. + +**Reference**: [Gitea Official Documentation](https://docs.gitea.com/) + +--- + +## What is Gitea? + +Gitea is a **painless, self-hosted, all-in-one software development service**. It includes: + +- Git hosting and repository management +- Code review (Pull Requests and AGit workflow) +- Issue tracking and project management +- CI/CD via Gitea Actions (compatible with GitHub Actions) +- Package registry (20+ package types: Cargo, npm, PyPI, Maven, etc.) +- Team collaboration tools + +**Key Point**: Gitea is similar to GitHub, Bitbucket, and GitLab, but is designed to be lightweight and self-hosted. + +--- + +## Core Features + +### 1. Code Hosting + +- Create and manage repositories +- Browse commit history and code files +- Review and merge code submissions +- Manage collaborators +- Handle branches, tags, cherry-picking, hooks +- Integrated collaboration tools + +### 2. Code Review + +- **Pull Request workflow** (same as GitHub) +- **AGit workflow** (Gitea-specific alternative) +- Online code browsing +- Review comments and feedback +- Inline code modifications + +### 3. Issue Tracking + +- Track requirements, features, and bugs +- Support for branches, tags, milestones +- Assignments, time tracking, due dates +- Dependencies between issues +- Project columns and boards + +### 4. CI/CD (Gitea Actions) + +- **Compatible with GitHub Actions** +- Write workflows in YAML format +- Reuse existing Actions plugins +- Actions plugins can be downloaded from any Git website +- Same `.github/workflows/` directory structure + +### 5. Package Registry + +Supports 20+ package types: +- Cargo, Chef, Composer, Conan, Conda +- Container, Helm, Maven, npm, NuGet +- Pub, PyPI, RubyGems, Vagrant +- And more + +### 6. Security + +- User permission management +- Access control lists (ACLs) +- Security-focused design +- Non-root system account recommended + +--- + +## System Requirements + +- **Minimum**: Raspberry Pi 3 (for small workloads) +- **Typical**: 2 CPU cores, 1GB RAM (for small teams/projects) +- **Git**: Version 2.0.0 or later required +- **Platforms**: Linux, macOS, Windows (x86, amd64, ARM, PowerPC) + +--- + +## Key Differences from GitHub + +### 1. Self-Hosted + +- Runs on your own infrastructure +- Full control over data and access +- No dependency on external services +- Can be air-gapped if needed + +### 2. Lightweight + +- Designed to be fast and resource-efficient +- Suitable for resource-limited environments +- Lower system requirements than GitHub/GitLab + +### 3. Open Source + +- MIT licensed +- Community-driven development +- Transparent codebase +- No vendor lock-in + +### 4. Actions Compatibility + +- Gitea Actions uses same format as GitHub Actions +- Workflows are largely interchangeable +- Some GitHub-specific features may not be available +- Actions can be sourced from any Git repository + +### 5. API Differences + +- Gitea API is similar to GitHub's but not identical +- Some endpoints may differ +- Authentication methods are similar +- Webhook formats are compatible + +--- + +## Terminology + +### Same as GitHub + +- **Repository** / **Repo** - Code storage +- **Branch** - Code versioning +- **Pull Request** / **PR** - Code review request +- **Issue** - Bug/feature tracking +- **Commit** - Code change +- **Tag** - Release marker +- **Fork** - Copy of repository +- **Clone** - Local copy + +### Gitea-Specific + +- **AGit workflow** - Alternative to Pull Request workflow +- **Gitea Actions** - CI/CD system (compatible with GitHub Actions) +- **Self-hosted** - Running on your own infrastructure + +--- + +## Common Workflows + +### Creating a Repository + +1. Log in to Gitea instance +2. Click "New Repository" +3. Configure repository settings +4. Push code or initialize with README + +### Creating a Pull Request + +1. Create a branch +2. Make changes and commit +3. Push branch to Gitea +4. Click "New Pull Request" +5. Review and merge (same as GitHub) + +### Using Gitea Actions + +1. Create `.github/workflows/` directory +2. Write workflow YAML (same format as GitHub Actions) +3. Push to repository +4. Gitea Actions will execute workflows + +### Managing Issues + +1. Create issue from repository +2. Assign to team members +3. Link to milestones, labels, projects +4. Track dependencies and due dates + +--- + +## For LLMs: Important Notes + +### When Documenting + +- Always refer to "Gitea" (not "GitHub") when the platform is Gitea +- Note that Gitea Actions is compatible with GitHub Actions +- Use Gitea terminology consistently +- Link to Gitea documentation: `https://docs.gitea.com/` + +### When Creating Workflows + +- Use `.github/workflows/` directory (same as GitHub) +- YAML format is identical to GitHub Actions +- Reference as "Gitea Actions workflows" +- Note compatibility in documentation + +### When Working with API + +- Gitea API is similar but not identical to GitHub's +- Check Gitea API documentation for specific endpoints +- Authentication uses tokens (similar to GitHub) +- Webhooks are compatible + +--- + +## References + +- **Gitea Documentation**: https://docs.gitea.com/ +- **Gitea Features**: https://docs.gitea.com/installation/comparison#general-features +- **Gitea Actions**: https://docs.gitea.com/usage/actions/ +- **Gitea API**: https://docs.gitea.com/api/ + +--- + +**Location**: `docs/GITEA/Gitea-Basics.md` +**Last Updated**: 2025-01-27 + diff --git a/docs/GITEA/Gitea-Workflows.md b/docs/GITEA/Gitea-Workflows.md new file mode 100644 index 0000000..e99c0a0 --- /dev/null +++ b/docs/GITEA/Gitea-Workflows.md @@ -0,0 +1,278 @@ +# Gitea Workflows for LLMs + +**Purpose**: Common workflows and best practices for working with Gitea repositories. + +**Reference**: [Gitea Usage Documentation](https://docs.gitea.com/usage/) + +--- + +## Common Workflows + +### 1. Repository Setup + +**Creating a new repository**: +1. Log in to Gitea instance +2. Click "New Repository" or "+" → "New Repository" +3. Configure repository settings: + - Name, description + - Visibility (public/private) + - Initialize with README (optional) + - Add .gitignore (optional) + - Choose license (optional) +4. Click "Create Repository" + +**Cloning a repository**: +```bash +git clone https://git.parkingmeter.info/owner/repo.git +cd repo +``` + +### 2. Branch Management + +**Creating a branch**: +```bash +git checkout -b feature/new-feature +git push -u origin feature/new-feature +``` + +**In Gitea UI**: +1. Go to repository +2. Click branch dropdown +3. Type new branch name +4. Click "Create Branch" + +### 3. Pull Requests + +**Creating a Pull Request**: +1. Push branch to Gitea +2. Click "New Pull Request" button (appears after push) +3. Select base branch (usually `main` or `master`) +4. Fill in PR title and description +5. Add reviewers, labels, milestones if needed +6. Click "Create Pull Request" + +**PR Workflow** (same as GitHub): +- Review code +- Add comments +- Request changes +- Approve +- Merge (merge, squash, or rebase) + +### 4. Issues + +**Creating an Issue**: +1. Go to repository +2. Click "Issues" tab +3. Click "New Issue" +4. Fill in title and description +5. Add labels, assignees, milestones +6. Click "Submit new issue" + +**Issue Features**: +- Assign to team members +- Link to milestones +- Add labels +- Set due dates +- Track dependencies +- Reference commits and PRs + +### 5. Gitea Actions (CI/CD) + +**Setting up workflows**: +1. Create `.github/workflows/` directory +2. Create workflow YAML file +3. Push to repository +4. Gitea Actions will execute workflows + +**Workflow triggers**: +- `push` - On push to repository +- `pull_request` - On PR events +- `workflow_dispatch` - Manual trigger +- `schedule` - Scheduled runs + +**Example workflow**: +```yaml +name: CI + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run tests + run: cargo test +``` + +--- + +## Best Practices + +### 1. Branch Naming + +**Conventions**: +- `feature/description` - New features +- `fix/description` - Bug fixes +- `docs/description` - Documentation +- `refactor/description` - Code refactoring +- `test/description` - Test improvements + +### 2. Commit Messages + +**Format**: `type(scope): description` + +**Types**: +- `feat` - New feature +- `fix` - Bug fix +- `docs` - Documentation +- `chore` - Maintenance +- `ci` - CI/CD changes + +**Examples**: +``` +feat(phase-01): Add Zapier integration +fix(phase-02): Resolve web link capture +docs(kb): add api-auth-decision and update index/changelog +``` + +### 3. Pull Request Process + +1. **Create feature branch** +2. **Make changes and commit** +3. **Push branch to Gitea** +4. **Create Pull Request** +5. **Request review** +6. **Address feedback** +7. **Merge when approved** + +### 4. Issue Management + +- Use labels for categorization +- Link issues to milestones +- Reference issues in commits: `Fixes #123` +- Close issues via PR: `Closes #123` + +--- + +## For LLMs: Workflow Documentation + +### When Documenting Workflows + +**Use Gitea terminology**: +```markdown +## Development Workflow + +1. Create a feature branch: `git checkout -b feature/name` +2. Make changes and commit +3. Push to Gitea: `git push origin feature/name` +4. Create Pull Request in Gitea +5. Request review and address feedback +6. Merge when approved +``` + +**Reference Gitea Actions**: +```markdown +## CI/CD Workflow + +This repository uses **Gitea Actions** for continuous integration. + +**Note**: Gitea Actions is compatible with GitHub Actions, so workflows +use the same YAML format and `.github/workflows/` directory structure. + +Workflows run automatically on: +- Push to main branch +- Pull requests +- Manual trigger via `workflow_dispatch` +``` + +### When Creating Workflow Files + +**Location and format**: +- Use `.github/workflows/` directory +- Use standard GitHub Actions YAML format +- Reference as "Gitea Actions workflows" in documentation + +**Example**: +```yaml +# Gitea Actions workflow +# Compatible with GitHub Actions format +name: Test + +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run tests + run: cargo test +``` + +--- + +## Integration with Documentation System + +### Phase Documentation + +When working with phase documentation: +- Reference Gitea repository URLs +- Use Gitea terminology in tasks.md +- Link to Gitea issues in tasks +- Reference Gitea Actions workflows + +### KB System + +When creating KB entries: +- Reference Gitea features when relevant +- Link to Gitea documentation +- Use Gitea terminology consistently + +### Cursor Rules + +When updating Cursor rules: +- Use "Gitea Actions" (not "GitHub Actions") +- Reference Gitea repository +- Note compatibility where relevant + +--- + +## Troubleshooting + +### Common Issues + +**Workflow not running**: +- Check runner registration +- Verify workflow syntax +- Check trigger conditions +- Review runner logs + +**PR not showing**: +- Verify branch was pushed +- Check branch visibility +- Verify base branch is correct + +**Issues not linking**: +- Use correct issue number format: `#123` +- Verify issue exists +- Check repository permissions + +--- + +## References + +- **Gitea Usage**: https://docs.gitea.com/usage/ +- **Gitea Actions**: https://docs.gitea.com/usage/actions/ +- **Pull Requests**: https://docs.gitea.com/usage/pull-request/ +- **Issues**: https://docs.gitea.com/usage/issues/ + +--- + +**Location**: `docs/GITEA/Gitea-Workflows.md` +**Last Updated**: 2025-01-27 + diff --git a/docs/GITEA/LLM-Gitea-Guidelines.md b/docs/GITEA/LLM-Gitea-Guidelines.md new file mode 100644 index 0000000..50a3574 --- /dev/null +++ b/docs/GITEA/LLM-Gitea-Guidelines.md @@ -0,0 +1,220 @@ +# LLM Guidelines for Working with Gitea + +**Purpose**: Specific guidelines for AI assistants (LLMs) when working with Gitea-based projects like Tendril. + +**Last Updated**: 2025-01-27 + +--- + +## Core Principles + +1. **Always refer to "Gitea"** (not "GitHub") when the platform is Gitea +2. **Note compatibility** when discussing Gitea Actions (compatible with GitHub Actions) +3. **Use Gitea terminology** consistently +4. **Link to Gitea documentation** when referencing features + +--- + +## Terminology Guidelines + +### Correct Usage + +✅ **Use These Terms**: +- "Gitea" - The platform +- "Gitea Actions" - CI/CD system +- "Gitea Runners" - CI/CD execution environment +- "Gitea instance" - Self-hosted Gitea server +- "Pull Request" or "PR" - Code review (same as GitHub) +- "Issues" - Bug/feature tracking (same as GitHub) +- "Repository" or "Repo" - Code storage (same as GitHub) + +❌ **Avoid These Terms** (when referring to Gitea): +- "GitHub" - Wrong platform +- "GitHub Actions" - Should be "Gitea Actions" (but note compatibility) +- "GitHub Runners" - Should be "Gitea Runners" +- "GitHub repository" - Should be "Gitea repository" + +### Compatibility Notes + +When discussing workflows or Actions: +- ✅ "Gitea Actions workflows (compatible with GitHub Actions format)" +- ✅ "Gitea Actions uses the same YAML format as GitHub Actions" +- ✅ "Workflows use `.github/workflows/` directory (same as GitHub)" + +--- + +## Documentation Standards + +### When Creating Documentation + +1. **Platform Reference**: + ```markdown + This repository uses **Gitea** for version control and collaboration. + ``` + +2. **Actions Reference**: + ```markdown + This project uses **Gitea Actions** for CI/CD. Gitea Actions is compatible + with GitHub Actions, so workflows use the same YAML format and + `.github/workflows/` directory structure. + ``` + +3. **Repository Links**: + ```markdown + Repository: https://git.parkingmeter.info/Mycelium/tendril + ``` + +### When Creating Workflow Files + +1. **File Location**: `.github/workflows/` (same as GitHub) +2. **YAML Format**: Identical to GitHub Actions +3. **Documentation**: Reference as "Gitea Actions workflows" +4. **Comments**: Note compatibility if relevant + +**Example**: +```yaml +# Gitea Actions workflow +# Compatible with GitHub Actions format +name: KB Lint + +on: + push: + paths: + - 'kb/**/*.md' +``` + +### When Updating Cursor Rules + +1. **Use "Gitea Actions"** in rules: + ```markdown + #### When Gitea Actions workflows (`.github/workflows/*.yml`) are modified: + ``` + +2. **Note compatibility**: + ```markdown + **Note**: Gitea Actions is compatible with GitHub Actions, so workflows + use the same YAML format and `.github/` directory structure. + ``` + +--- + +## Common Scenarios + +### Scenario 1: Creating a New Workflow + +**What to do**: +1. Create workflow in `.github/workflows/` +2. Use standard GitHub Actions YAML format +3. Document as "Gitea Actions workflow" +4. Note compatibility in documentation +5. Update `.github/CHANGELOG.md` +6. Update `.github/README.md` + +**Example documentation**: +```markdown +### KB Lint Workflow + +**File**: `.github/workflows/kb-lint.yml` + +**Purpose**: Validates KB file naming and frontmatter + +**Platform**: Gitea Actions (compatible with GitHub Actions format) + +**Triggers**: Runs on push and pull requests when KB files change +``` + +### Scenario 2: Referencing Repository + +**What to do**: +1. Use Gitea repository URL +2. Reference as "Gitea repository" +3. Link to Gitea instance + +**Example**: +```markdown +**Repository**: https://git.parkingmeter.info/Mycelium/tendril +**Platform**: Gitea (self-hosted) +``` + +### Scenario 3: Discussing Features + +**What to do**: +1. Reference Gitea features +2. Note similarities to GitHub when helpful +3. Link to Gitea documentation + +**Example**: +```markdown +Gitea supports Pull Requests (similar to GitHub) and also provides +an AGit workflow alternative. For more information, see the +[Gitea documentation](https://docs.gitea.com/). +``` + +--- + +## File Structure Guidelines + +### Workflow Files + +- **Location**: `.github/workflows/` +- **Format**: YAML (same as GitHub Actions) +- **Naming**: `kebab-case.yml` +- **Documentation**: Reference as "Gitea Actions workflows" + +### Documentation Files + +- **Location**: `.github/` or project root +- **Content**: Use "Gitea" terminology +- **Links**: Link to Gitea documentation when relevant + +### Cursor Rules + +- **Location**: `.cursorrules` or `.cursor/rules/` +- **Content**: Use "Gitea Actions" (not "GitHub Actions") +- **Notes**: Include compatibility notes where relevant + +--- + +## Checklist for LLMs + +When working with Gitea-based projects: + +- [ ] Use "Gitea" (not "GitHub") when referring to the platform +- [ ] Use "Gitea Actions" (not "GitHub Actions") but note compatibility +- [ ] Reference Gitea repository URLs correctly +- [ ] Link to Gitea documentation: `https://docs.gitea.com/` +- [ ] Note compatibility when discussing workflows +- [ ] Use `.github/workflows/` directory (same as GitHub) +- [ ] Use standard GitHub Actions YAML format for workflows +- [ ] Update `.github/CHANGELOG.md` when modifying workflows +- [ ] Update `.github/README.md` when adding workflows +- [ ] Use Gitea terminology consistently + +--- + +## Quick Reference + +### Repository Information + +- **Platform**: Gitea (self-hosted) +- **Instance**: git.parkingmeter.info +- **Repository**: https://git.parkingmeter.info/Mycelium/tendril + +### Documentation Links + +- **Gitea Docs**: https://docs.gitea.com/ +- **Gitea Actions**: https://docs.gitea.com/usage/actions/ +- **Gitea API**: https://docs.gitea.com/api/ + +### Key Points + +1. Gitea is self-hosted (not GitHub) +2. Gitea Actions is compatible with GitHub Actions +3. Workflows use same format and directory structure +4. Terminology should reference "Gitea" consistently + +--- + +**Location**: `docs/GITEA/LLM-Gitea-Guidelines.md` +**Related**: `docs/AGENT-GUIDELINES.md`, `.cursorrules` + diff --git a/docs/GITEA/README.md b/docs/GITEA/README.md new file mode 100644 index 0000000..b6f5e96 --- /dev/null +++ b/docs/GITEA/README.md @@ -0,0 +1,106 @@ +# Gitea Documentation for LLMs + +**Purpose**: This directory contains documentation to help AI assistants (LLMs) understand and work with Gitea, a self-hosted Git service. + +**Last Updated**: 2025-01-27 + +--- + +## Overview + +**Gitea** is a painless, self-hosted, all-in-one software development service. It includes Git hosting, code review, team collaboration, package registry, and CI/CD. It is similar to GitHub, Bitbucket and GitLab. + +**Key Reference**: [Gitea Official Documentation](https://docs.gitea.com/) + +--- + +## Contents + +- **[Gitea-Basics.md](./Gitea-Basics.md)** - Core concepts, features, and how Gitea differs from GitHub +- **[Gitea-Actions-Guide.md](./Gitea-Actions-Guide.md)** - Gitea Actions (CI/CD) compatibility and usage +- **[Gitea-Workflows.md](./Gitea-Workflows.md)** - Common workflows and best practices +- **[Gitea-API-Reference.md](./Gitea-API-Reference.md)** - API differences and considerations +- **[LLM-Gitea-Guidelines.md](./LLM-Gitea-Guidelines.md)** - Guidelines for LLMs working with Gitea + +--- + +## Quick Reference + +### What is Gitea? + +Gitea is a self-hosted Git service that provides: +- Git hosting and repository management +- Code review (Pull Requests and AGit workflow) +- Issue tracking and project management +- CI/CD via Gitea Actions (compatible with GitHub Actions) +- Package registry (20+ package types) +- Team collaboration tools + +### Key Differences from GitHub + +1. **Self-Hosted**: Gitea runs on your own infrastructure +2. **Lightweight**: Designed to be fast and resource-efficient +3. **Open Source**: MIT licensed, community-driven +4. **Actions Compatibility**: Gitea Actions uses the same YAML format as GitHub Actions +5. **API Compatibility**: Gitea API is similar to GitHub's but has some differences + +### Gitea Actions Compatibility + +**Critical**: Gitea Actions is compatible with GitHub Actions: +- Same `.github/workflows/` directory structure +- Same YAML workflow format +- Same triggers and syntax +- Existing GitHub Actions workflows work with minimal or no modifications +- Actions plugins can be downloaded from any Git website + +**Reference**: [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/) + +--- + +## For LLMs Working with Gitea + +### Terminology + +- Use **"Gitea"** (not "GitHub") when referring to the platform +- Use **"Gitea Actions"** (not "GitHub Actions") but note compatibility +- Use **"Pull Request"** or **"PR"** (same as GitHub) +- Use **"Issues"** (same as GitHub) +- Use **"Repository"** or **"Repo"** (same as GitHub) + +### Documentation References + +When creating documentation: +- Reference Gitea-specific features when relevant +- Note GitHub Actions compatibility when discussing workflows +- Use Gitea terminology consistently +- Link to Gitea documentation: `https://docs.gitea.com/` + +### Workflow Files + +- Workflows use `.github/workflows/` directory (same as GitHub) +- YAML format is identical to GitHub Actions +- Reference as "Gitea Actions workflows" in documentation +- Note compatibility: "Gitea Actions is compatible with GitHub Actions" + +--- + +## Repository Context + +**Tendril Repository**: https://git.parkingmeter.info/Mycelium/tendril +**Gitea Instance**: Self-hosted at git.parkingmeter.info +**Primary Platform**: Gitea (not GitHub) + +--- + +## Additional Resources + +- **Official Gitea Docs**: https://docs.gitea.com/ +- **Gitea Actions**: https://docs.gitea.com/usage/actions/ +- **Gitea API**: https://docs.gitea.com/api/ +- **Gitea Source**: https://gitea.com/gitea/gitea + +--- + +**Location**: `docs/GITEA/` +**Maintained by**: Tendril Project Maintainers + diff --git a/docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md b/docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md new file mode 100644 index 0000000..9e3bba1 --- /dev/null +++ b/docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md @@ -0,0 +1,2437 @@ +# Complete System Replication Guide +## Comprehensive Documentation System for Cursor + LLM Projects + +**Purpose**: This document contains everything needed to replicate the PAIRS documentation and automation system in another project. It includes all structures, schemas, templates, rationale, and step-by-step instructions. + +**Last Updated**: 2025-01-27 + +--- + +## Table of Contents + +1. [System Overview](#system-overview) +2. [Cursor Rules System](#cursor-rules-system) +3. [Phase Documentation System](#phase-documentation-system) +4. [Knowledge Base (KB) System](#knowledge-base-kb-system) +5. [GitHub Automation System](#github-automation-system) +6. [LLM Usage Guides](#llm-usage-guides) +7. [Schemas and Validation](#schemas-and-validation) +8. [File Structure and Conventions](#file-structure-and-conventions) +9. [Decision Rationale](#decision-rationale) +10. [Step-by-Step Replication Guide](#step-by-step-replication-guide) +11. [Templates](#templates) +12. [Troubleshooting](#troubleshooting) + +--- + +## System Overview + +### What This System Provides + +This documentation system creates a comprehensive, LLM-friendly project structure that includes: + +- **Phase-based project management** with synchronized documentation +- **Knowledge Base (KB) system** for capturing and organizing external information +- **Automated workflows** via GitHub Actions +- **Cursor rules** for consistent AI agent behavior +- **LLM usage guides** for prompt-based workflows +- **Decision tracking** via ADRs (Architecture Decision Records) +- **Change tracking** via changelogs +- **Task management** synchronized with GitHub issues + +### 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 + +### System Architecture + +``` +Project Root/ +├── .cursorrules # Main Cursor rules file +├── .cursor/rules/ # Individual Project Rules (alternative) +├── .github/ # GitHub Actions and automation docs +│ ├── workflows/ # GitHub Actions workflows +│ ├── README.md # .github directory overview +│ ├── CHANGELOG.md # Workflow change tracking +│ ├── decisions.md # Automation decisions +│ └── LLM-Usage-Guide--{REPO}.md # Per-repo LLM guide +├── docs/ # Project documentation +│ ├── AGENT-GUIDELINES.md # AI agent rules +│ └── PROMPTS/ # LLM prompt documents +├── pairs/ # Main project directory (customize name) +│ ├── phases/ # Phase documentation +│ │ └── phase-XX-name/ +│ │ ├── blueprint.md # Phase blueprint +│ │ ├── tasks.md # Task tracking +│ │ ├── decisions.md # ADRs +│ │ └── changelog.md # Change history +│ └── research/ # Research materials +└── kb/ # Knowledge Base system + ├── 01_projects/ # 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 + ├── _guides/ # KB system guides + ├── _templates/ # KB file templates + ├── _inbox/ # Unclassified content + ├── _review_queue/ # Low-confidence routing + ├── _index.md # Auto-generated index + └── scripts/ # KB automation scripts +``` + +--- + +## Cursor Rules System + +### Overview + +Cursor rules control how AI agents (like Cursor AI) behave in your project. There are two approaches: + +1. **Single `.cursorrules` file** - Traditional approach, all rules in one file +2. **Project Rules (`.cursor/rules/*.mdc`)** - Modern approach, individual rule files + +### Approach 1: Single `.cursorrules` File + +**Location**: `.cursorrules` (root of repository) + +**Complete Content** (with annotations): + +```markdown +# Cursor Rules for [PROJECT NAME] + +## Phase Documentation Synchronization Rules + +### MANDATORY: When blueprint.md is modified, automatically update related phase documents + +When ANY file matching `pairs/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 GitHub 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 `[project-name]` - customize for your 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 (`pairs/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 GitHub 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:** GitHub 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 +``` + +### Approach 2: Project Rules (`.cursor/rules/*.mdc`) + +**Location**: `.cursor/rules/` directory + +**File Format**: Each rule is a separate `.mdc` file with frontmatter + +**Example Rule File** (`.cursor/rules/phase-documentation-workflow.mdc`): + +```markdown +--- +alwaysApply: true +--- +When editing any phase blueprint.md, immediately check and update: changelog.md, tasks.md, and decisions.md in the same phase directory. Always verify project name consistency across all phase documents. Update README.md phase statuses when phase status changes (✅ Complete, 🔄 In Progress, ⏳ Planned). +``` + +**Individual Rules to Create**: + +1. **`phase-documentation-workflow.mdc`** + - Content: Phase documentation synchronization rules + +2. **`kb-system-usage.mdc`** + - Content: KB system usage and index check requirements + +3. **`file-structure-conventions.mdc`** + - Content: File naming and structure conventions + +4. **`commit-message-standards.mdc`** + - Content: Conventional commit message format + +5. **`adhd-friendly-workflow.mdc`** + - Content: Break work into small chunks, incremental updates + +6. **`github-automation-maintenance.mdc`** + - Content: .github folder update requirements + +**Setup Instructions**: + +1. Create `.cursor/rules/` directory in project root +2. For each rule, create a `.mdc` file with: + - Frontmatter: `---\nalwaysApply: true\n---` + - Rule content on line 4 +3. Cursor automatically loads rules when repository is opened + +**Rationale**: Project Rules allow better organization and easier maintenance of individual rules, while `.cursorrules` is simpler for single-file management. + +--- + +## Phase Documentation System + +### Overview + +Phase documentation provides structured project management with four synchronized documents per phase: +- `blueprint.md` - Complete phase specification +- `tasks.md` - Task tracking (mirrors GitHub issues) +- `decisions.md` - Architecture Decision Records (ADRs) +- `changelog.md` - Change history + +### Directory Structure + +``` +pairs/phases/ # or customize: project/phases/ +├── phase-00-foundation/ +│ ├── blueprint.md +│ ├── tasks.md +│ ├── decisions.md +│ └── changelog.md +├── phase-01-next-phase/ +│ └── [same structure] +└── ... +``` + +### Blueprint Template + +**File**: `pairs/phases/phase-XX-name/blueprint.md` + +**Complete Template**: + +```markdown +# Project Phase Document: Phase X - [Phase Name] + +**Project:** [Project Name] +**Phase:** Phase X: [Phase Name] +**Project Manager:** [Name] +**Technical Lead:** [Name] +**Start Date:** YYYY-MM-DD +**End Date:** YYYY-MM-DD +**Version:** 1.0 +**Status:** ✅ Complete | 🔄 In Progress | ⏳ Planned + +--- + +## 1. Phase Overview + +### 1.1. Executive Summary +[2-3 paragraph summary of what this phase accomplishes and why it matters] + +### 1.2. Phase Goals & Success Criteria + +**Business Goals:** +- [Goal 1] +- [Goal 2] + +**Technical Goals:** +- [Goal 1] +- [Goal 2] + +**Success Metrics (KPIs):** +- ✅ [Metric 1] +- ✅ [Metric 2] + +**Definition of Done:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +--- + +## 2. Scope & Deliverables + +### 2.1. In-Scope Items +- [Item 1] +- [Item 2] + +### 2.2. Out-of-Scope Items +- [Item 1] +- [Item 2] + +### 2.3. Phase Deliverables +- [ ] [Deliverable 1] +- [ ] [Deliverable 2] + +--- + +## 3. Technical Specifications + +### 3.1. System Architecture +[Description of architecture for this phase] + +### 3.2. Technology Stack +- **Programming Languages & Frameworks:** [List] +- **Database:** [Description] +- **Infrastructure & Hosting:** [Description] +- **APIs & Integrations:** [List] + +### 3.3. Coding Standards & Best Practices +- [Standard 1] +- [Standard 2] + +### 3.4. Data Models & Schemas +- [Schema description or reference] + +--- + +## 4. Team & Resource Allocation + +| **Role** | **Name** | **Responsibilities** | +| :--- | :--- | :--- | +| Project Owner | [Name] | [Responsibilities] | +| Technical Lead | [Name] | [Responsibilities] | + +### 4.2. Resource Requirements +- [Requirement 1] +- [Requirement 2] + +--- + +## 5. Timeline & Milestones + +| **Milestone** | **Target Date** | **Status** | +| :--- | :--- | :--- | +| [Milestone 1] | YYYY-MM-DD | ✅ Completed | +| [Milestone 2] | YYYY-MM-DD | 🔄 In Progress | + +--- + +## 6. Risk Management + +| **Risk Description** | **Likelihood (1-5)** | **Impact (1-5)** | **Mitigation Strategy** | **Contingency Plan** | +| :--- | :--- | :--- | :--- | :--- | +| [Risk 1] | [1-5] | [1-5] | [Strategy] | [Plan] | + +--- + +## 7. Communication & Reporting + +### 7.1. Meeting Cadence +- **Daily:** [Frequency] +- **Phase Retrospective:** [When] + +### 7.2. Reporting +- [Reporting method] + +--- + +## 8. Quality Assurance & Testing + +### 8.1. Testing Strategy +- ✅ [Test 1] +- ✅ [Test 2] + +### 8.2. Test Environments +- **Development:** [Description] +- **Production:** [Description] + +--- + +## 9. Opportunities for Improvement & Lessons Learned + +### 9.1. Process Improvements +- [Improvement 1] +- [Improvement 2] + +### 9.2. Technology & Tool Suggestions +- [Suggestion 1] +- [Suggestion 2] + +### 9.3. Lessons Learned +- [Lesson 1] +- [Lesson 2] + +--- + +## 10. Phase Sign-off + +### 10.1. Approval Criteria +- [x] All deliverables completed +- [x] Documentation up to date +- [x] Ready for next phase + +### 10.2. Approvers +- **Project Owner:** [Name] + +### 10.3. Sign-off Date +**YYYY-MM-DD** — Phase complete and ready for next phase + +--- + +**Next Phase:** [Phase X+1 - Next Phase Name](./../phase-XX-next/blueprint.md) +``` + +### Tasks Template + +**File**: `pairs/phases/phase-XX-name/tasks.md` + +**Complete Template**: + +```markdown +# Phase X – Tasks (Mirror of GitHub Issues) + +This document tracks all actionable items for **Phase X: [Phase Name]**, mirroring corresponding GitHub issues and providing a low-friction view for progress tracking. + +--- + +## 🔧 [Category Name] + +* [ ] **PX-001:** [Task description] + +* [ ] **PX-002:** [Task description] + +--- + +## 📜 [Category Name] + +* [ ] **PX-003:** [Task description] + +--- + +## ✅ Completion Criteria + +To mark Phase X as complete: + +* [ ] [Criterion 1] + +* [ ] [Criterion 2] + +--- + +**Linked Documents:** + +* Blueprint: [Phase X – [Phase Name]](./blueprint.md) + +--- + +*Use this list during daily and weekly reviews. Update checkboxes as tasks are completed or issues are closed in GitHub.* +``` + +### Decisions Template + +**File**: `pairs/phases/phase-XX-name/decisions.md` + +**Complete Template**: + +```markdown +# Phase X – Architectural Decisions (ADRs) + +## ADR-000: [Decision Title] + +**Status:** Accepted | Proposed | Deprecated | Superseded +**Date:** YYYY-MM-DD + +**Context:** [What problem or need prompted this decision] + +**Decision:** [What was decided] + +**Consequences:** +- ✅ [Positive consequence] +- ⚠️ [Warning or trade-off] + +--- + +## ADR-001: [Next Decision] + +[Same format as above] + +--- +``` + +### Changelog Template + +**File**: `pairs/phases/phase-XX-name/changelog.md` + +**Complete Template**: + +```markdown +# Phase X – Changelog + +- **YYYY-MM-DD:** [Description of change] +- **YYYY-MM-DD:** [Description of change] +- **YYYY-MM-DD:** [Description of change] + +``` + +**Format Rules**: +- One entry per line +- Date format: `YYYY-MM-DD` +- Use format: `- **YYYY-MM-DD:** [Description]` +- Most recent entries at top (optional, but recommended) + +### Synchronization Rules + +**When `blueprint.md` is modified:** + +1. **Update `changelog.md`**: + - Add entry: `- **YYYY-MM-DD:** [Description of blueprint changes]` + - Include: project name changes, milestone updates, scope changes, status changes + +2. **Sync `tasks.md`**: + - Align checkboxes with blueprint "Definition of Done" items + - Align task list with blueprint "Phase Deliverables" section + - Update phase status if blueprint status changed + +3. **Review `decisions.md`**: + - Add ADR if blueprint reflects new architectural decision + - Verify existing ADRs still align with blueprint specifications + +4. **Verify consistency**: + - Project name matches across all documents + - Dates are consistent + - Status indicators are aligned + +**Rationale**: Keeping documents synchronized ensures no information is lost and all documentation stays current. This is critical for LLM agents that rely on documentation accuracy. + +--- + +## Knowledge Base (KB) System + +### Overview + +The KB system provides a lightweight, LLM-friendly staging area for external information that may inform project development. It uses structured routing, confidence scoring, and automatic indexing. + +### Directory Structure + +``` +kb/ +├── 01_projects/ # Project-specific notes +│ ├── [project-name]/ # Current project notes +│ └── _shared/ # Cross-project notes +├── 02_systems/ # Infrastructure, DevOps, tooling +├── 03_research/ # Informal research, links +├── 04_design/ # Product specs, UX, copy +├── 05_decisions/ # ADR-style decisions +├── 06_glossary/ # Terms, acronyms +├── 07_playbooks/ # How-to guides, SOPs +├── 08_archive/ # Superseded content +├── _guides/ # KB system guidelines (read-only) +│ └── KB_INGEST_PROMPT.md # System prompt for ingestion +├── _templates/ # File templates (read-only) +│ ├── note.md +│ ├── decision.md +│ └── howto.md +├── _inbox/ # Unclassified content (rare) +├── _review_queue/ # Low-confidence routing (<0.60) +├── _index.md # Auto-generated searchable index +├── CHANGELOG.md # KB change tracking +├── README.md # KB system documentation +└── scripts/ + └── generate-index.sh # Index generation script +``` + +### File Naming Schema + +**Pattern**: `YYYY-MM-DD--slug--type.md` + +**Components**: +- **Date (YYYY-MM-DD)**: Date content was created or captured +- **Slug**: 3-8 lowercase words, hyphen-joined, no stop-words (a, an, the, and, or, but, etc.) +- **Type**: One of: `idea`, `note`, `spec`, `decision`, `howto`, `retro`, `meeting` +- **Multi-part files**: Append `--p1`, `--p2`, etc. for long content + +**Examples**: +- ✅ `2025-11-06--api-authentication-flow--spec.md` +- ✅ `2025-11-06--user-onboarding-decision--decision.md` +- ❌ `api-design.md` (missing date and type) +- ❌ `2025-11-06--the-api--note.md` (contains stop-word "the") + +**Regex Pattern**: +``` +^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$ +``` + +### Frontmatter Schema + +**18 Required Fields**: + +```yaml +--- +title: "Descriptive title in sentence case" +date: "YYYY-MM-DD" # Must match filename date +captured_at: "YYYY-MM-DD" # Same as date (project compatibility) +author: ["author name"] # Array, default ["unknown author"] +source: { kind: pulse|chat|web|doc, ref: "" } +source_type: voice|web|pdf|image|personal_note|chat|pulse +project: ["project-name"] # Array, customize for your project +related_projects: ["project-name"] # Same as project (compatibility) +topics: ["topic1", "topic2"] # Array of 2-5 topic keywords +tags: ["tag1", "tag2"] # Array of 2-8 tags +type: idea|note|spec|decision|howto|retro|meeting # Must match filename type +status: draft|active|archived +phase_relevance: ["phase-01", "phase-02"] # Array of relevant phases or [] +routing_hint: "Brief explanation of routing decision" +proposed_path: "kb/XX_category/" # Where LLM intends to file it +routing_confidence: 0.87 # Numeric 0.00-1.00 +related: [] # Array of related file paths +summary: "One to three sentence summary of the content" +--- +``` + +**Optional Fields**: +```yaml +key_takeaways: ["takeaway1", "takeaway2"] +action_candidates: ["action1", "action2"] +``` + +### Routing Decision Tree + +1. **Is it project-specific?** → `/kb/01_projects/[project]/` or `_shared/` +2. **Is it a how-to or procedure?** → `/kb/07_playbooks/` +3. **Is it a decision with rationale?** → `/kb/05_decisions/` +4. **Is it about infrastructure/tooling?** → `/kb/02_systems/` +5. **Is it research or external reference?** → `/kb/03_research/` +6. **Is it design/UX/copy?** → `/kb/04_design/` +7. **Is it a definition or term?** → `/kb/06_glossary/` +8. **Is it obsolete?** → `/kb/08_archive/` (only if truly superseded) +9. **Unclear?** → `/kb/_inbox/` (should be rare) + +### Routing Confidence System + +**Confidence Levels**: +- **0.90–1.00**: Crystal clear placement - content clearly matches category +- **0.75–0.89**: Good guess - content fits well but might have minor ambiguity +- **0.60–0.74**: Uncertain - content could fit multiple categories, needs review +- **<0.60**: Low confidence - unclear routing, send to `_review_queue/` instead of proposed path + +**Policy**: If `routing_confidence < 0.60`, the file MUST be placed in `kb/_review_queue/` instead of the proposed path, but still include `proposed_path` in frontmatter for human review. + +### KB File Templates + +#### Note Template + +**File**: `kb/_templates/note.md` + +```markdown +--- +title: "${TITLE}" +date: "${DATE}" +captured_at: "${DATE}" +author: ["${AUTHOR}"] +source: { kind: ${SRC_KIND}, ref: "${SRC_REF}" } +source_type: ${SOURCE_TYPE} +project: [${PROJECTS}] +related_projects: [${PROJECTS}] +topics: [${TOPICS}] +tags: [${TAGS}] +type: note +status: draft +phase_relevance: [${PHASE_RELEVANCE}] +routing_hint: "${ROUTING_HINT}" +proposed_path: "kb/XX_category/" +routing_confidence: 0.75 +related: [${RELATED}] +summary: "${SUMMARY}" +key_takeaways: [] +action_candidates: [] +--- + +# Context + +# Key Points + +# Key Takeaways + +# Action Candidates + +# Actions / Next Steps + +# References +``` + +#### Decision Template + +**File**: `kb/_templates/decision.md` + +```markdown +--- +title: "${TITLE}" +date: "${DATE}" +captured_at: "${DATE}" +author: ["${AUTHOR}"] +source: { kind: ${SRC_KIND}, ref: "${SRC_REF}" } +source_type: ${SOURCE_TYPE} +project: [${PROJECTS}] +related_projects: [${PROJECTS}] +topics: [${TOPICS}] +tags: [decision, ${TAGS}] +type: decision +status: active +phase_relevance: [${PHASE_RELEVANCE}] +routing_hint: "${ROUTING_HINT}" +proposed_path: "kb/05_decisions/" +routing_confidence: 0.90 +related: [${RELATED}] +summary: "${SUMMARY}" +key_takeaways: [] +action_candidates: [] +--- + +## Decision + +## Context + +## Options Considered + +## Rationale + +## Consequences + +## Key Takeaways + +## Action Candidates + +## Revisit Date +``` + +#### HowTo Template + +**File**: `kb/_templates/howto.md` + +```markdown +--- +title: "${TITLE}" +date: "${DATE}" +captured_at: "${DATE}" +author: ["${AUTHOR}"] +source: { kind: ${SRC_KIND}, ref: "${SRC_REF}" } +source_type: ${SOURCE_TYPE} +project: [${PROJECTS}] +related_projects: [${PROJECTS}] +topics: [${TOPICS}] +tags: [howto, ${TAGS}] +type: howto +status: active +phase_relevance: [${PHASE_RELEVANCE}] +routing_hint: "${ROUTING_HINT}" +proposed_path: "kb/07_playbooks/" +routing_confidence: 0.90 +related: [${RELATED}] +summary: "${SUMMARY}" +key_takeaways: [] +action_candidates: [] +--- + +## Steps + +1. + +2. + +3. + +## Verification + +## Rollback + +## Key Takeaways + +## Action Candidates +``` + +### KB Ingestion Prompt + +**File**: `kb/_guides/KB_INGEST_PROMPT.md` + +**Purpose**: System prompt for LLM-assisted KB ingestion + +**Complete Content**: [See full content in templates section below - this is a large file that should be copied exactly] + +### Index Generation + +**Script**: `kb/scripts/generate-index.sh` + +**Purpose**: Generates `kb/_index.md` with searchable metadata + +**Key Features**: +- Scans all KB files +- Extracts frontmatter metadata +- Generates topics index, tags index, phase relevance index +- Updates automatically via GitHub Actions + +**Manual Execution**: +```bash +kb/scripts/generate-index.sh +``` + +**Auto-Update**: GitHub Actions workflow (`.github/workflows/kb-index-update.yml`) runs on push to main when KB files change. + +--- + +## GitHub Automation System + +### Overview + +The `.github/` directory contains GitHub Actions workflows and documentation for repository automation. It follows a structured documentation pattern that keeps automation decisions and changes tracked. + +### Directory Structure + +``` +.github/ +├── workflows/ # GitHub Actions workflows +│ ├── daily-pulse.yml # Example: Daily automation +│ ├── kb-lint.yml # KB file validation +│ ├── kb-index-update.yml # KB index auto-update +│ └── [other-workflows].yml +├── README.md # .github directory overview +├── CHANGELOG.md # Workflow change tracking +├── decisions.md # Automation decisions +└── LLM-Usage-Guide--{REPO}.md # Per-repo LLM instructions +``` + +### .github/README.md Template + +```markdown +# .github Directory + +_Last updated: YYYY-MM-DD_ + +## Purpose + +The `.github/` directory contains GitHub Actions workflows, issue templates, and documentation for repository automation and maintenance. + +--- + +## Contents + +### Workflows (`workflows/`) + +GitHub Actions workflows that automate various aspects of the repository: + +- **`[workflow-name].yml`** - [Description] + +### Documentation + +- **`README.md`** (this file) - Overview of .github directory structure and purpose +- **`CHANGELOG.md`** - Tracks all changes to workflows and .github folder +- **`decisions.md`** - Documents decisions about workflows, automation, and GitHub Actions +- **`LLM-Usage-Guide--{REPO-NAME}.md`** - LLM instructions for this repository's workflows and automation + +--- + +## Workflow Overview + +### [Workflow Name] +- **Schedule**: [When it runs] +- **Purpose**: [What it does] +- **Output**: [What it produces] + +--- + +## Maintenance + +### When Adding New Workflows + +1. **Update `CHANGELOG.md`** - Document the new workflow and its purpose +2. **Update `decisions.md`** - Document why this workflow was added +3. **Update this README** - Add workflow to the overview section +4. **Update `LLM-Usage-Guide--{REPO-NAME}.md`** - Add instructions for the new workflow + +### When Modifying Existing Workflows + +1. **Update `CHANGELOG.md`** - Document what changed and why +2. **Update `decisions.md`** - Document the decision behind the change +3. **Test workflow** - Verify changes work as expected +4. **Update documentation** - Ensure README and LLM guide reflect changes + +### When Removing Workflows + +1. **Update `CHANGELOG.md`** - Document removal and reason +2. **Update `decisions.md`** - Document why workflow was removed +3. **Update this README** - Remove from overview +4. **Update `LLM-Usage-Guide--{REPO-NAME}.md`** - Remove references + +--- + +**Location**: `.github/` +**Maintained by**: [Your Name] +``` + +### .github/CHANGELOG.md Template + +```markdown +# Changelog — .github Directory + +All notable changes to workflows, automation, and .github folder structure. + +## [YYYY-MM-DD] Brief Description + +### Added +- **`[file-path]`** - [Description] + +### Changed +- **`[file-path]`** - [Description of change] + +### Fixed +- **`[file-path]`** - [Bug fix description] + +### Notes +- [Additional context or important information] + +--- + +## [Previous Date] Previous Change + +[Same format as above] + +--- +``` + +### .github/decisions.md Template + +```markdown +# Decisions — .github Directory + +_Last updated: YYYY-MM-DD_ + +## Purpose + +This document tracks decisions made about GitHub Actions workflows, automation, and the .github directory structure. Decisions are documented with context, rationale, and alternatives considered. + +--- + +## Decision Format + +Each decision entry includes: +- **Date**: When the decision was made +- **Context**: What problem or need prompted this decision +- **Decision**: What was decided +- **Rationale**: Why this approach was chosen +- **Alternatives**: Other options considered +- **Impact**: What this affects + +--- + +## Decisions + +### [YYYY-MM-DD] Decision Title + +**Context**: [What prompted this decision] + +**Decision**: [What was decided] + +**Rationale**: +- [Reason 1] +- [Reason 2] + +**Alternatives Considered**: +- [Alternative 1] - [Why not chosen] +- [Alternative 2] - [Why not chosen] + +**Impact**: +- [Impact 1] +- [Impact 2] + +--- + +## Future Decisions + +Decisions about new workflows, automation changes, or .github structure modifications should be added here with the same format. + +--- + +**Location**: `.github/decisions.md` +**Maintained by**: [Your Name] +``` + +### .github/LLM-Usage-Guide Template + +**File**: `.github/LLM-Usage-Guide--{REPO-NAME}.md` + +**Naming Convention**: Use `LLM-Usage-Guide--{REPO-NAME}.md` where `{REPO-NAME}` is your repository name. This enables automated sync scripts to identify target repos. + +**Template**: + +```markdown +# LLM Usage Guide for GitHub Workflows — {REPO-NAME} + +_Last updated: YYYY-MM-DD_ + +## Purpose + +This guide provides instructions for AI assistants (LLMs) on how to work with GitHub Actions workflows, automation, and the `.github/` directory structure in this repository. + +--- + +## Repository Context + +**Repository**: `{repo-name}` +**Primary System**: [System name] +**Automation Focus**: [What this repo automates] + +--- + +## Understanding .github Directory Structure + +### Workflows (`workflows/`) + +GitHub Actions workflows automate repository operations: + +- **`[workflow-name].yml`** - [Description] + +### Documentation + +- **`README.md`** - Overview of .github directory and workflows +- **`CHANGELOG.md`** - Tracks all changes to workflows and .github folder +- **`decisions.md`** - Documents decisions about workflows and automation +- **`LLM-Usage-Guide--{REPO-NAME}.md`** (this file) - LLM instructions for this repo + +--- + +## Working with Workflows + +### When Modifying Workflows + +**MANDATORY**: When any workflow file is modified: + +1. **Update `.github/CHANGELOG.md`**: + - Add entry with date and description + - Document what changed and why + - Include affected workflow name + +2. **Update `.github/decisions.md`** (if decision-related): + - Document the decision behind the change + - Explain rationale and alternatives considered + - Note impact on automation + +3. **Update `.github/README.md`** (if structure changes): + - Update workflow descriptions if behavior changed + - Add new workflows to overview + - Remove references to deleted workflows + +4. **Test the workflow**: + - Use `workflow_dispatch` trigger if available + - Verify expected behavior + - Check for errors in Actions tab + +### When Adding New Workflows + +1. Create workflow file in `.github/workflows/` +2. Update `.github/CHANGELOG.md` - Document new workflow +3. Update `.github/decisions.md` - Document why workflow was added +4. Update `.github/README.md` - Add to workflow overview +5. Test workflow - Verify it runs successfully +6. Update this guide - Add instructions if needed + +--- + +## Workflow-Specific Instructions + +### [Workflow Name] + +**File**: `.github/workflows/[workflow-name].yml` + +**Purpose**: [What it does] + +**When to modify**: +- [Condition 1] +- [Condition 2] + +**Validation**: +- [Check 1] +- [Check 2] + +--- + +## Documentation Maintenance + +### .github/CHANGELOG.md + +**Purpose**: Track all changes to workflows and .github folder + +**Format**: +```markdown +## [YYYY-MM-DD] Brief Description + +### Added +- New workflow or feature + +### Changed +- Modified workflow behavior + +### Fixed +- Bug fix or correction +``` + +**When to update**: Every time a workflow file is modified + +### .github/decisions.md + +**Purpose**: Document decisions about workflows and automation + +**Format**: +```markdown +### [YYYY-MM-DD] Decision Title + +**Context**: What prompted this decision +**Decision**: What was decided +**Rationale**: Why this approach +**Alternatives**: Other options considered +**Impact**: What this affects +``` + +**When to update**: When making significant workflow decisions + +--- + +## Common Tasks + +### Adding a New Workflow + +1. Create workflow file in `.github/workflows/` +2. Add workflow to `.github/README.md` overview +3. Document in `.github/CHANGELOG.md` +4. Document decision in `.github/decisions.md` (if applicable) +5. Test workflow with `workflow_dispatch` +6. Commit all changes together + +### Modifying an Existing Workflow + +1. Make workflow changes +2. Update `.github/CHANGELOG.md` with change description +3. Update `.github/decisions.md` if decision-related +4. Update `.github/README.md` if behavior changed significantly +5. Test workflow +6. Commit changes + +--- + +## Validation Checklist + +Before committing workflow changes: + +- [ ] Workflow file syntax is valid YAML +- [ ] Workflow tested with `workflow_dispatch` (if available) +- [ ] `.github/CHANGELOG.md` updated with change description +- [ ] `.github/decisions.md` updated (if decision-related) +- [ ] `.github/README.md` updated (if structure/behavior changed) +- [ ] All changes committed together +- [ ] Commit message follows conventional format: `ci(workflows): description` + +--- + +**Repository**: `{repo-name}` +**Location**: `.github/LLM-Usage-Guide--{REPO-NAME}.md` +**Maintained by**: [Your Name] +``` + +### Example Workflow: KB Lint + +**File**: `.github/workflows/kb-lint.yml` + +**Purpose**: Validates KB file naming, frontmatter, and structure + +**Complete Workflow** (see validation section for full details): + +```yaml +name: KB Lint + +on: + push: + paths: + - 'kb/**/*.md' + pull_request: + paths: + - 'kb/**/*.md' + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate KB Files + run: | + # Validation script (see Schemas and Validation section) +``` + +--- + +## LLM Usage Guides + +### Overview + +LLM Usage Guides are prompt documents that provide step-by-step instructions for AI assistants to perform specific tasks. They are designed for drag-and-drop use in Cursor chat. + +### Prompt Document Structure + +**Location**: `docs/PROMPTS/` + +**Naming Convention**: `NN-Descriptive-Name-Prompt.md` where NN is zero-padded two-digit number (00, 01, 02, etc.) + +**Example**: `01-Project-Status-Check-Prompt.md` + +### Prompt Document Template + +```markdown +# [Task Name] Prompt + +**Purpose:** [One sentence describing what this prompt accomplishes] + +**How to Use:** Drag this entire document into a Cursor chat session, then [provide context/information]. The AI assistant will follow these instructions to [accomplish the task]. + +--- + +## CRITICAL: Information Gathering + +### Required Information (You should provide this) + +Before starting, **ASK THE USER** for the following information if not already provided: + +1. **[Information Item 1]** (REQUIRED) + - Format/constraints + - Examples + - Why it's needed + +2. **[Information Item 2]** (REQUIRED) + - ... + +### If Information is Missing + +**ALWAYS ASK** for missing required information before proceeding. Do not make assumptions about: +- [List of things not to assume] + +--- + +## Step-by-Step Process + +### Phase 1: [Phase Name] + +[Description of what this phase accomplishes] + +1. **Step description:** + ```bash + # Commands or code + ``` + +2. **Validation:** + - How to verify this step succeeded + - What to check + +### Phase 2: [Phase Name] + +... + +--- + +## Error Handling + +### Common Issues + +#### [Issue Name] +- **Error message**: What you'll see +- **Fix**: How to resolve it +- **Prevention**: How to avoid it + +--- + +## Validation Checklist + +Before completing, verify: + +- [ ] [Checklist item 1] +- [ ] [Checklist item 2] +- [ ] ... + +--- + +## Important Notes for AI Assistant + +1. **[Critical instruction 1]** +2. **[Critical instruction 2]** +3. ... +``` + +### LLM Usage Guide for Prompts + +**File**: `docs/PROMPTS/LLM-Usage-Guide.md` + +**Purpose**: Instructions for LLMs on how to recognize, interpret, and execute prompt documents + +**Key Sections**: +- Recognizing Prompt Documents +- Executing Prompts (Phase-by-Phase) +- Information Gathering +- Error Handling +- Validation Steps +- Providing Feedback + +**Complete Template**: [See full content in templates section below] + +### Prompt Creation Guide + +**File**: `docs/PROMPTS/Prompt-Creation-Guide.md` + +**Purpose**: Guide for creating effective, reusable prompt documents + +**Key Sections**: +- Naming Convention +- Prompt Structure Template +- Best Practices +- Writing Effective Instructions +- Testing Your Prompt +- Common Patterns + +**Complete Template**: [See full content in templates section below] + +--- + +## Schemas and Validation + +### KB File Validation Rules + +**Filename Pattern**: +``` +^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$ +``` + +**Frontmatter Requirements**: +- Must have YAML frontmatter delimited by `---` +- All 18 required fields must be present +- Date in frontmatter must match filename date +- Type in frontmatter must match filename type +- `routing_confidence` must be numeric 0.00-1.00 +- Files with `routing_confidence < 0.60` must be in `_review_queue/` + +**Validation Script Logic** (for GitHub Actions): + +```bash +# Validate filename pattern +if ! [[ "$filename" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}--[a-z0-9-]+--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$ ]]; then + echo "❌ ERROR: Invalid filename pattern" + exit 1 +fi + +# Extract date and type from filename +filename_date=$(echo "$filename" | sed -E 's/^([0-9]{4}-[0-9]{2}-[0-9]{2})--.*/\1/') +filename_type=$(echo "$filename" | sed -E 's/.*--([a-z]+)(--p[0-9]+)?\.md$/\1/') + +# Check frontmatter exists +if ! grep -q "^---$" "$file"; then + echo "❌ ERROR: Missing frontmatter delimiter" + exit 1 +fi + +# Extract frontmatter +frontmatter=$(sed -n '/^---$/,/^---$/p' "$file" | sed '1d;$d') + +# Check required fields +REQUIRED_FIELDS=("title" "date" "author" "source" "project" "topics" "tags" "type" "status" "routing_hint" "proposed_path" "routing_confidence" "related" "summary") +for field in "${REQUIRED_FIELDS[@]}"; do + if ! echo "$frontmatter" | grep -q "^${field}:"; then + echo "❌ ERROR: Missing required field: $field" + exit 1 + fi +done + +# Validate date matches +frontmatter_date=$(echo "$frontmatter" | grep "^date:" | sed -E 's/^date:[[:space:]]*["'\'']?([^"'\'']+)["'\'']?.*/\1/' | tr -d ' ') +if [ "$frontmatter_date" != "$filename_date" ]; then + echo "❌ ERROR: Date mismatch" + exit 1 +fi + +# Validate type matches +frontmatter_type=$(echo "$frontmatter" | grep "^type:" | sed -E 's/^type:[[:space:]]*["'\'']?([^"'\'']+)["'\'']?.*/\1/' | tr -d ' ') +if [ "$frontmatter_type" != "$filename_type" ]; then + echo "❌ ERROR: Type mismatch" + exit 1 +fi + +# Validate routing_confidence +routing_confidence=$(echo "$frontmatter" | grep "^routing_confidence:" | sed -E 's/^routing_confidence:[[:space:]]*([0-9.]+).*/\1/' | tr -d ' ') +if ! awk -v conf="$routing_confidence" 'BEGIN {if (conf < 0.0 || conf > 1.0 || conf == "") exit 1}' 2>/dev/null; then + echo "❌ ERROR: Invalid routing_confidence value" + exit 1 +fi + +# Enforce review queue policy +if awk -v conf="$routing_confidence" 'BEGIN {exit !(conf < 0.60)}' 2>/dev/null; then + if [[ "$file" != *"/_review_queue/"* ]]; then + echo "❌ ERROR: File has routing_confidence < 0.60 but is not in kb/_review_queue/" + exit 1 + fi +fi +``` + +### Phase Blueprint Schema + +**Required Sections**: +1. Phase Overview (Executive Summary, Goals, Success Criteria, Definition of Done) +2. Scope & Deliverables (In-Scope, Out-of-Scope, Deliverables) +3. Technical Specifications (Architecture, Technology Stack, Coding Standards, Data Models) +4. Team & Resource Allocation +5. Timeline & Milestones +6. Risk Management +7. Communication & Reporting +8. Quality Assurance & Testing +9. Opportunities for Improvement & Lessons Learned +10. Phase Sign-off + +**Status Values**: `✅ Complete`, `🔄 In Progress`, `⏳ Planned` + +**Date Format**: `YYYY-MM-DD` + +### Research Note Schema + +**File Naming**: `YYYY-MM-DD-title.md` + +**Frontmatter Requirements** (project-specific, customize as needed): +```yaml +--- +title: "Title" +captured_at: "YYYY-MM-DD" +source_type: voice|web|pdf|image|personal_note|chat|pulse +tags: ["tag1", "tag2"] +phase_relevance: ["phase-01", "phase-02"] +--- +``` + +--- + +## File Structure and Conventions + +### Directory Naming + +- **Phase directories**: `phase-XX-name` where XX is zero-padded number (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 Conventions + +- **Phase documentation**: `blueprint.md`, `tasks.md`, `decisions.md`, `changelog.md` +- **KB files**: `YYYY-MM-DD--slug--type.md` +- **Research notes**: `YYYY-MM-DD-title.md` +- **Scripts**: `kebab-case.sh` or `.py` +- **Workflows**: `kebab-case.yml` + +### Markdown Formatting Standards + +- Use consistent heading levels (## for main sections, ### for subsections) +- Include YAML front-matter for all structured documents +- Use tables for structured data (tasks, risks, milestones) +- Link between related documents using relative paths +- Use code fences with language tags for code blocks + +### Git 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` +- `ci(workflows): update kb-lint validation rules` + +--- + +## Decision Rationale + +### Why Phase Documentation Synchronization is Mandatory + +**Problem**: Documentation drifts apart over time, leading to inconsistencies and confusion. + +**Solution**: Mandatory synchronization rules ensure related documents stay in sync automatically. + +**Benefits**: +- No information loss +- Consistent project state +- LLM agents have accurate context +- Reduced manual maintenance + +**Trade-offs**: +- Requires discipline to follow rules +- Initial setup overhead +- But: Prevents much larger problems later + +### Why KB System Exists Alongside Research System + +**Problem**: Need different systems for different types of content. + +**Solution**: Two complementary systems: +- **KB system**: Lightweight, informal, LLM-friendly staging area +- **Research system**: Formal, structured, full metadata schema + +**Benefits**: +- Right tool for right content +- Clear separation of concerns +- KB can feed into research system +- Different validation rules for each + +**Rationale**: Not all content needs full research treatment. KB provides quick capture, research provides deep analysis. + +### Why Routing Confidence System + +**Problem**: LLM routing decisions aren't always perfect, need human review for uncertain cases. + +**Solution**: Confidence scoring (0.00-1.00) with automatic routing to review queue for low confidence (<0.60). + +**Benefits**: +- Catches routing mistakes early +- Allows human review of uncertain items +- Provides feedback loop for improving routing +- Prevents misclassified content from getting lost + +**Rationale**: Better to flag uncertain items than silently misroute them. + +### Why Two-Phase Status Report Architecture + +**Problem**: LLM-generated reports were incomplete (extraction issues) and expensive (full formatting). + +**Solution**: Two-phase architecture: +- Phase 1: Script generates complete raw reports (reliable, complete) +- Phase 2: LLM adds only analytical sections (smaller, cheaper) + +**Benefits**: +- 60-70% reduction in LLM token usage +- Complete reports every time (no extraction issues) +- Faster generation (smaller LLM calls) +- PMO-ready structured JSON +- Can review raw data before LLM processing + +**Rationale**: Separation of data gathering (script) and analysis (LLM) provides better reliability and cost efficiency. + +### Why Cursor Rules System + +**Problem**: Need consistent AI agent behavior across project. + +**Solution**: Comprehensive `.cursorrules` file or Project Rules with mandatory synchronization and validation rules. + +**Benefits**: +- Consistent agent behavior +- Automatic documentation synchronization +- Reduced manual oversight +- Better project maintenance + +**Rationale**: AI agents need clear rules to follow. Well-structured rules prevent common mistakes and ensure quality. + +--- + +## Step-by-Step Replication Guide + +### Prerequisites + +- GitHub repository (new or existing) +- Cursor IDE installed +- Git configured +- Basic understanding of Markdown and YAML + +### Phase 1: Create Directory Structure + +1. **Create main directories**: + ```bash + mkdir -p .github/workflows + mkdir -p docs/PROMPTS + mkdir -p pairs/phases # or customize: project/phases/ + mkdir -p kb/{01_projects,02_systems,03_research,04_design,05_decisions,06_glossary,07_playbooks,08_archive,_guides,_templates,_inbox,_review_queue,scripts} + ``` + +2. **Create phase directory structure**: + ```bash + mkdir -p pairs/phases/phase-00-foundation + # Repeat for each phase + ``` + +3. **Verify structure**: + ```bash + tree -L 3 # or use ls -R + ``` + +### Phase 2: Set Up Cursor Rules + +**Option A: Single `.cursorrules` File** + +1. Create `.cursorrules` in project root +2. Copy complete `.cursorrules` content from "Cursor Rules System" section above +3. Customize project name and paths +4. Save file + +**Option B: Project Rules (`.cursor/rules/*.mdc`)** + +1. Create `.cursor/rules/` directory +2. For each rule, create `.mdc` file with: + - Frontmatter: `---\nalwaysApply: true\n---` + - Rule content +3. See "Cursor Rules System" section for individual rules + +### Phase 3: Create Phase Documentation Templates + +1. **Create first phase directory**: + ```bash + mkdir -p pairs/phases/phase-00-foundation + ``` + +2. **Create blueprint.md**: + - Copy template from "Phase Documentation System" section + - Customize for your project + - Fill in Phase 0 details + +3. **Create tasks.md**: + - Copy template from "Phase Documentation System" section + - Add initial tasks + +4. **Create decisions.md**: + - Copy template from "Phase Documentation System" section + - Add initial ADRs if any + +5. **Create changelog.md**: + - Copy template from "Phase Documentation System" section + - Add initial entry + +### Phase 4: Set Up KB System + +1. **Create KB directory structure** (already done in Phase 1) + +2. **Create KB README.md**: + ```bash + cp [template] kb/README.md + # Or create from template in "KB System" section + ``` + +3. **Create KB templates**: + ```bash + # Copy templates from "KB System" section + # Create kb/_templates/note.md + # Create kb/_templates/decision.md + # Create kb/_templates/howto.md + ``` + +4. **Create KB ingestion prompt**: + ```bash + # Copy KB_INGEST_PROMPT.md content from templates section + # Create kb/_guides/KB_INGEST_PROMPT.md + ``` + +5. **Create index generation script**: + ```bash + # Copy generate-index.sh from KB system section + # Create kb/scripts/generate-index.sh + chmod +x kb/scripts/generate-index.sh + ``` + +6. **Create KB CHANGELOG.md**: + ```bash + # Create kb/CHANGELOG.md with initial entry + ``` + +### Phase 5: Configure GitHub Actions + +1. **Create .github/README.md**: + - Copy template from "GitHub Automation System" section + - Customize for your workflows + +2. **Create .github/CHANGELOG.md**: + - Copy template from "GitHub Automation System" section + - Add initial entry + +3. **Create .github/decisions.md**: + - Copy template from "GitHub Automation System" section + +4. **Create .github/LLM-Usage-Guide--{REPO-NAME}.md**: + - Copy template from "GitHub Automation System" section + - Replace {REPO-NAME} with your repository name + +5. **Create workflows** (examples): + - `.github/workflows/kb-lint.yml` - KB validation + - `.github/workflows/kb-index-update.yml` - KB index auto-update + - Add other workflows as needed + +### Phase 6: Create LLM Usage Guides + +1. **Create docs/PROMPTS/ directory** (already done in Phase 1) + +2. **Create LLM-Usage-Guide.md**: + - Copy template from "LLM Usage Guides" section + - Customize for your project + +3. **Create Prompt-Creation-Guide.md**: + - Copy template from "LLM Usage Guides" section + +4. **Create initial prompt documents**: + - Use naming convention: `NN-Descriptive-Name-Prompt.md` + - Start with `00-` for first prompt + +### Phase 7: Validation and Testing + +1. **Test Cursor rules**: + - Open project in Cursor + - Verify rules are loaded (check Cursor settings) + - Test by editing a blueprint.md and verifying synchronization + +2. **Test KB system**: + - Create a test KB file + - Run index generation: `kb/scripts/generate-index.sh` + - Verify `kb/_index.md` is generated + - Test KB lint workflow (if configured) + +3. **Test phase documentation**: + - Edit a blueprint.md + - Verify changelog.md, tasks.md, decisions.md are checked/updated + - Verify README.md is checked + +4. **Test GitHub Actions**: + - Push changes to trigger workflows + - Verify workflows run successfully + - Check that documentation is updated + +### Phase 8: Customization + +1. **Customize project name**: + - Replace "PAIRS" or placeholder names throughout + - Update all references in documentation + +2. **Customize directory names**: + - If not using "pairs/", update all references + - Update Cursor rules paths + +3. **Customize phase structure**: + - Adjust phase numbering if needed + - Customize phase names + +4. **Customize KB categories**: + - Adjust category names if needed + - Update routing decision tree + +5. **Add project-specific rules**: + - Add to `.cursorrules` or Project Rules + - Document in appropriate guides + +--- + +## Templates + +### Complete KB Ingestion Prompt + +**File**: `kb/_guides/KB_INGEST_PROMPT.md` + +**Complete Content** (copy this exactly): + +```markdown +# KB Ingestion System Prompt + +**Use this prompt in Cursor before pasting content to be ingested into the Knowledge Base.** + +--- + +## System Instructions + +You are a Knowledge Base ingestion assistant. Your role is to analyze incoming content (from "Pulse Daily" chats, ideas, notes, etc.) and route it to the appropriate location in the `/kb/` directory structure with proper naming, frontmatter, and formatting. + +## Classification and Routing Rules + +Content must be routed to one of these directories based on its primary purpose: + +- **`/kb/01_projects/[project-name]/`** - Project-specific notes, tasks, or updates +- **`/kb/01_projects/_shared/`** - Cross-project notes that apply to multiple projects +- **`/kb/02_systems/`** - Infrastructure, DevOps, tooling, technical systems, architecture decisions +- **`/kb/03_research/`** - Links, papers, competitor notes, external research, learning materials +- **`/kb/04_design/`** - Product specs, UX design, copy, user experience, interface design +- **`/kb/05_decisions/`** - ADR-style decisions with rationale, architectural decisions, strategic choices +- **`/kb/06_glossary/`** - Terms, acronyms, definitions, vocabulary +- **`/kb/07_playbooks/`** - How-to guides, SOPs, runbooks, procedures, operational guides +- **`/kb/08_archive/`** - Old or superseded content (use sparingly, prefer deletion if truly obsolete) +- **`/kb/_inbox/`** - Use only if content cannot be clearly classified (should be rare) +- **`/kb/_review_queue/`** - Low-confidence routing items requiring human review (routing_confidence < 0.60) + +### Routing Decision Tree + +1. **Is it project-specific?** → `/kb/01_projects/[project]/` or `_shared/` +2. **Is it a how-to or procedure?** → `/kb/07_playbooks/` +3. **Is it a decision with rationale?** → `/kb/05_decisions/` +4. **Is it about infrastructure/tooling?** → `/kb/02_systems/` +5. **Is it research or external reference?** → `/kb/03_research/` +6. **Is it design/UX/copy?** → `/kb/04_design/` +7. **Is it a definition or term?** → `/kb/06_glossary/` +8. **Is it obsolete?** → `/kb/08_archive/` (only if truly superseded) +9. **Unclear?** → `/kb/_inbox/` (should be rare) + +### Routing Confidence Assessment + +After determining the proposed routing destination, you MUST assess your confidence level: + +- **0.90–1.00:** Crystal clear placement - content clearly matches category, type, and purpose +- **0.75–0.89:** Good guess - content fits well but might have minor ambiguity +- **0.60–0.74:** Uncertain - content could fit multiple categories, needs review +- **<0.60:** Low confidence - unclear routing, send to `_review_queue/` instead of proposed path + +**Routing Policy:** If `routing_confidence < 0.60`, the file MUST be placed in `kb/_review_queue/` instead of the proposed path, but still include `proposed_path` in frontmatter for human review. + +## File Naming Standards + +**Format:** `YYYY-MM-DD--slug--type.md` + +### Components + +- **Date (YYYY-MM-DD):** Use the date the content was created or captured (today's date if unknown) +- **Slug:** 3-8 lowercase words, hyphen-joined, no stop-words (a, an, the, and, or, but, etc.) + - Good: `user-authentication-flow`, `api-rate-limiting-strategy`, `cursor-workflow-setup` + - Bad: `the-api`, `a-user`, `and-authentication` +- **Type:** One of: `idea`, `note`, `spec`, `decision`, `howto`, `retro`, `meeting` +- **Multi-part files:** If content is too long, append `--p1`, `--p2`, etc. to the filename + - Example: `2025-11-06--comprehensive-api-design--spec--p1.md` + +### Type Selection + +- **`idea`** - New concepts, proposals, brainstorming +- **`note`** - General notes, observations, thoughts +- **`spec`** - Specifications, requirements, detailed plans +- **`decision`** - ADR-style decisions (should go in `/kb/05_decisions/`) +- **`howto`** - Step-by-step guides (should go in `/kb/07_playbooks/`) +- **`retro`** - Retrospectives, post-mortems, lessons learned +- **`meeting`** - Meeting notes, summaries + +## Frontmatter Requirements + +Every KB file MUST have complete YAML frontmatter with all required fields. The base system requires 14 fields, but projects may add additional fields (like `captured_at`, `source_type`, `related_projects`, `phase_relevance` for PAIRS). + +**Base Required Fields (14):** +```yaml +--- +title: "Descriptive title in sentence case" +date: "YYYY-MM-DD" +author: ["author name"] # Array, default to ["unknown author"] if unknown +source: { kind: pulse|chat|web|doc, ref: "" } +project: ["project-name"] # Array, customize for your project +topics: [] # Array of topic keywords +tags: [] # Array of tags for categorization +type: idea|note|spec|decision|howto|retro|meeting +status: draft|active|archived +routing_hint: "Brief explanation of why this was routed here" +proposed_path: "kb/XX_category/" # Where LLM intends to file it +routing_confidence: 0.87 # Numeric value 0.00-1.00 +related: [] # Array of related file paths or references +summary: "One to three sentence summary of the content" +--- +``` + +**Optional Project-Specific Fields** (add as needed): +- `captured_at` - Same as date (for compatibility) +- `source_type` - voice|web|pdf|image|personal_note|chat|pulse +- `related_projects` - Same as project (for compatibility) +- `phase_relevance` - Array of relevant phases (e.g., `["phase-01", "phase-02"]`) +- `key_takeaways` - Array of key insights +- `action_candidates` - Array of potential action items + +### Field Guidelines + +- **title:** Clear, descriptive, sentence case (not title case) +- **date:** Must match filename date prefix (YYYY-MM-DD) +- **author:** Array format, use `["unknown author"]` if unknown +- **source:** Object with `kind` (pulse, chat, web, doc) and `ref` (link, ID, or identifier) +- **project:** Array, customize for your project, expandable for future projects +- **topics:** Array of 2-5 topic keywords (e.g., `["authentication", "security", "api"]`) +- **tags:** Array of 2-8 tags for cross-cutting categorization (e.g., `["backend", "urgent", "review-needed"]`) +- **type:** Must match filename type suffix exactly +- **status:** `draft` for new content, `active` for current/relevant, `archived` for old +- **routing_hint:** Brief explanation (1-2 sentences) of routing decision +- **proposed_path:** The directory path where the LLM intends to file the content +- **routing_confidence:** Numeric value between 0.00 and 1.00 indicating confidence in the routing decision +- **related:** Array of related file paths or references +- **summary:** Concise 1-3 sentence summary of the content + +## Output Format + +**CRITICAL:** You MUST output your response in a JSON code block with this exact structure: + +```json +{ + "file_path": "kb/XX_category/YYYY-MM-DD--slug--type.md", + "frontmatter": { + "title": "...", + "date": "YYYY-MM-DD", + "author": ["..."], + "source": { "kind": "...", "ref": "..." }, + "project": ["..."], + "topics": ["..."], + "tags": ["..."], + "type": "...", + "status": "...", + "routing_hint": "...", + "proposed_path": "kb/XX_category/", + "routing_confidence": 0.87, + "related": [], + "summary": "..." + }, + "content": "# Title\n\n[Markdown content here]" +} +``` + +**IMPORTANT:** The `file_path` in the JSON output MUST reflect the actual destination: +- If `routing_confidence >= 0.60`: Use the `proposed_path` as the actual `file_path` +- If `routing_confidence < 0.60`: Use `kb/_review_queue/` as the actual `file_path` (but still include `proposed_path` in frontmatter) + +## Quality and Style Guidelines + +1. **Content Quality:** + - Preserve original meaning and intent + - Improve clarity and structure without changing substance + - Use proper Markdown formatting (headers, lists, code blocks) + - Break long content into logical sections + +2. **Writing Style:** + - Use clear, concise language + - Prefer active voice + - Use proper grammar and spelling + - Maintain professional tone + +3. **Structure:** + - Start with a clear title (H1) + - Use H2 for major sections + - Use H3 for subsections + - Include a summary section if helpful + - Add "Related" section for cross-references + +4. **Markdown Best Practices:** + - Use fenced code blocks with language tags + - Use proper list formatting + - Use links for references + - Use emphasis (bold/italic) sparingly + +## Safety Constraints + +**NEVER:** +- Modify files in `/kb/_guides/` or `/kb/_templates/` +- Overwrite existing files without explicit user permission +- Create files outside `/kb/` directory structure +- Skip frontmatter validation +- Use invalid filename patterns +- Create duplicate files (check existing files first) + +**ALWAYS:** +- Validate filename matches pattern: `YYYY-MM-DD--slug--type.md` +- Ensure all required frontmatter fields are present +- Verify date in frontmatter matches filename date +- Verify type in frontmatter matches filename type +- Check for existing similar files to avoid duplicates +- Use appropriate routing based on content purpose +- Assess routing confidence honestly (0.00-1.00) +- Route low-confidence items (<0.60) to `kb/_review_queue/` instead of proposed path + +## Example Workflow + +1. User pastes content into Cursor +2. You analyze the content to determine: + - Primary purpose and routing destination + - Appropriate type (idea, note, spec, etc.) + - Key topics and tags + - Related content + - **Routing confidence level (0.00-1.00)** +3. You generate: + - Proper filename following naming standards + - Complete frontmatter with all required fields + - Well-structured Markdown content +4. You determine actual file path: + - If `routing_confidence >= 0.60`: Use `proposed_path` as actual destination + - If `routing_confidence < 0.60`: Use `kb/_review_queue/` as actual destination +5. You output JSON code block with file_path, frontmatter, and content +6. User (or automation) creates the file from your JSON output + +## Validation Checklist + +Before outputting JSON, verify: + +- [ ] Filename matches pattern: `YYYY-MM-DD--slug--type.md` +- [ ] All required frontmatter fields are present +- [ ] Date in frontmatter matches filename date +- [ ] Type in frontmatter matches filename type +- [ ] Routing confidence is assessed honestly (0.00-1.00) +- [ ] `proposed_path` is set to intended destination directory +- [ ] Actual `file_path` reflects routing policy (if confidence < 0.60, use `kb/_review_queue/`) +- [ ] Routing destination is appropriate for content +- [ ] Content is well-structured Markdown +- [ ] Summary accurately describes the content +- [ ] Topics and tags are relevant and useful +- [ ] Related references are valid (if any) + +--- + +## Completion Summary and Reporting + +**CRITICAL:** After outputting the JSON code block, you MUST also provide a completion summary in markdown format with the following sections: + +### What Was Accomplished + +- **File Created**: `kb/XX_category/YYYY-MM-DD--slug--type.md` +- **Routing Decision**: [Brief explanation of why this content was routed to this category] +- **Content Type**: [type] in [category] +- **File Status**: [draft/active/archived] + +### KB File Details + +- **Title**: [title from frontmatter] +- **Type**: [type from frontmatter] +- **Topics**: [list of topics from frontmatter] +- **Tags**: [list of tags from frontmatter] +- **Summary**: [summary from frontmatter] +- **Author**: [author from frontmatter] +- **Source**: [source kind and ref from frontmatter] + +### Possible Uses in Project + +- [How this KB can be used in project planning/development] +- [Related workflows or decisions this informs] +- [Potential integrations with other systems or documentation] +- [Who might benefit from this knowledge] + +### Local Document Update Report + +**MANDATORY STEPS:** After creating the KB file, you must: + +1. **Update Index**: + - Run: `kb/scripts/generate-index.sh` + - This regenerates `kb/_index.md` with the new file's metadata + - Verify the script completes successfully + - Check that the new file appears in `kb/_index.md` + +2. **Update Changelog**: + - Add entry to `kb/CHANGELOG.md` with the following format: + ```markdown + ## [YYYY-MM-DD] KB File Added + + ### Added + - `kb/XX_category/YYYY-MM-DD--slug--type.md` - [Brief description of content] + ``` + - 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 the KB file contains + +3. **Commit Changes**: + - Commit all three changes together: + - The new KB file + - The updated `kb/_index.md` + - The updated `kb/CHANGELOG.md` + - Use commit message: `docs(kb): add [filename-slug] and update index/changelog` + - Example: `docs(kb): add api-auth-decision and update index/changelog` + +**Status Checklist:** +- [ ] KB file created at correct path +- [ ] Index updated: `kb/scripts/generate-index.sh` run successfully +- [ ] Changelog updated: Entry added to `kb/CHANGELOG.md` +- [ ] All changes committed together +- [ ] Commit message follows format: `docs(kb): add [filename-slug] and update index/changelog` + +**Note:** If you cannot run the index generation script or update the changelog automatically, clearly indicate what needs to be done manually in the "Local Document Update Report" section. + +--- + +**Remember:** The goal is to create well-organized, discoverable knowledge that can be easily found and referenced later. Take time to classify correctly and provide complete metadata. Always update the index and changelog after creating KB files. +``` + +**Note**: Customize the project name references (`[project-name]`) and add any project-specific frontmatter fields as needed for your project. + +### Complete LLM Usage Guide for Prompts + +**File**: `docs/PROMPTS/LLM-Usage-Guide.md` + +**Purpose**: Instructions for LLMs on how to recognize, interpret, and execute prompt documents + +**Key Sections** (copy complete content from original `docs/PROMPTS/LLM-Usage-Guide.md` file): +- Recognizing Prompt Documents +- Executing Prompts (Phase-by-Phase Execution) +- Information Gathering +- Error Handling +- Validation Steps +- Providing Feedback +- Best Practices +- Special Instructions +- Troubleshooting + +**Note**: The complete file is quite extensive. Copy the entire content from the original `docs/PROMPTS/LLM-Usage-Guide.md` file in the PAIRS project, or use the template structure shown in the "LLM Usage Guides" section above as a starting point. + +### Complete Prompt Creation Guide + +**File**: `docs/PROMPTS/Prompt-Creation-Guide.md` + +**Purpose**: Guide for creating effective, reusable prompt documents + +**Key Sections** (copy complete content from original `docs/PROMPTS/Prompt-Creation-Guide.md` file): +- Naming Convention +- Prompt Structure Template +- Best Practices +- Writing Effective Instructions +- Testing Your Prompt +- Common Patterns +- When to Create a New Prompt +- Updating Existing Prompts +- Checklist for New Prompts + +**Note**: The complete file is quite extensive. Copy the entire content from the original `docs/PROMPTS/Prompt-Creation-Guide.md` file in the PAIRS project, or use the template structure shown in the "LLM Usage Guides" section above as a starting point. + +--- + +## Troubleshooting + +### Cursor Rules Not Applying + +**Symptoms**: AI agent doesn't follow rules, documentation not synchronized + +**Solutions**: +1. Verify `.cursorrules` file exists in project root +2. Check Cursor settings → Rules, Memories, Commands → Project Rules +3. If using Project Rules, verify `.cursor/rules/*.mdc` files have correct frontmatter +4. Restart Cursor +5. Check file paths in rules match your directory structure + +### KB Validation Failures + +**Symptoms**: GitHub Actions KB lint workflow fails + +**Solutions**: +1. Check filename matches pattern: `YYYY-MM-DD--slug--type.md` +2. Verify all 18 required frontmatter fields are present +3. Check date in frontmatter matches filename date +4. Check type in frontmatter matches filename type +5. Verify `routing_confidence` is numeric 0.00-1.00 +6. If confidence < 0.60, verify file is in `_review_queue/` + +### Phase Documentation Out of Sync + +**Symptoms**: Blueprint, tasks, decisions, changelog don't match + +**Solutions**: +1. Manually review all four documents +2. Update changelog.md with current date and description of discrepancies +3. Sync tasks.md with blueprint.md "Definition of Done" and "Phase Deliverables" +4. Review decisions.md for missing ADRs mentioned in blueprint +5. Verify project name matches across all documents +6. Check status indicators are aligned + +### KB Index Not Updating + +**Symptoms**: `kb/_index.md` doesn't reflect new KB files + +**Solutions**: +1. Run index generation manually: `kb/scripts/generate-index.sh` +2. Check script has execute permissions: `chmod +x kb/scripts/generate-index.sh` +3. Verify GitHub Actions workflow is configured and running +4. Check workflow logs for errors +5. Verify KB files have valid frontmatter (index script requires it) + +### GitHub Actions Workflow Failures + +**Symptoms**: Workflows fail to run or produce errors + +**Solutions**: +1. Check workflow YAML syntax is valid +2. Verify workflow triggers are correct (paths, events) +3. Check required secrets are configured +4. Review workflow logs for specific error messages +5. Test workflow with `workflow_dispatch` trigger +6. Verify file paths in workflow match actual structure + +### LLM Prompt Not Executing Correctly + +**Symptoms**: AI assistant doesn't follow prompt instructions + +**Solutions**: +1. Verify prompt document is complete (all sections present) +2. Check prompt follows template structure +3. Ensure "CRITICAL" and "MANDATORY" sections are clearly marked +4. Verify information gathering section requests all required data +5. Test prompt with a simple task first +6. Review LLM-Usage-Guide.md for execution guidelines + +--- + +## Conclusion + +This guide provides everything needed to replicate the PAIRS documentation and automation system in another project. Key takeaways: + +1. **Start with structure** - Create directories first +2. **Set up rules early** - Cursor rules ensure consistency +3. **Use templates** - All templates are provided above +4. **Validate frequently** - Automated validation catches issues early +5. **Document decisions** - ADRs and changelogs track evolution +6. **Keep synchronized** - Mandatory sync rules prevent drift + +**Next Steps**: +1. Review this guide completely +2. Follow Step-by-Step Replication Guide +3. Customize for your project +4. Test each component +5. Iterate and improve + +**Questions or Issues?** +- Review Troubleshooting section +- Check original PAIRS project for examples +- Refer to specific sections above for detailed information + +--- + +**Document Version**: 1.0 +**Last Updated**: 2025-01-27 +**Maintained by**: [Your Name] +**Based on**: PAIRS-for-the-Individual project documentation system + diff --git a/docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md b/docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md new file mode 100644 index 0000000..6ac4fe9 --- /dev/null +++ b/docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md @@ -0,0 +1,62 @@ +# Phase 0 Gitea Updates Summary + +**Date**: 2025-01-27 +**Purpose**: Document updates made to Phase 0 files to reflect Gitea (self-hosted) instead of GitHub + +## Changes Made + +### 1. `.cursorrules` File Updates + +**Updated References:** +- "GitHub Actions workflows" → "Gitea Actions workflows" (3 occurrences) +- "GitHub Actions will auto-update" → "Gitea Actions will auto-update" + +**Note**: Gitea Actions is compatible with GitHub Actions, so the `.github/workflows/` directory structure and YAML format remain the same. + +### 2. `docs/AGENT-GUIDELINES.md` Updates + +**Updated References:** +- "GitHub issues" → "Gitea issues" +- "GitHub Automation" → "Gitea Automation" (section title) +- "GitHub Actions workflows" → "Gitea Actions workflows (compatible with GitHub Actions format)" +- "When Modifying GitHub Workflows" → "When Modifying Gitea Actions Workflows" +- Added note: "Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure." +- Added 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." +- "GitHub automation" → "Gitea automation" (in Getting Help section) + +## Key Points + +1. **Gitea Actions Compatibility**: Gitea Actions is compatible with GitHub Actions, meaning: + - Same `.github/workflows/` directory structure + - Same YAML workflow format + - Same triggers and syntax + - Existing GitHub Actions workflows can be used with minimal or no modifications + +2. **Repository Context**: + - Primary repository: https://git.parkingmeter.info/Mycelium/tendril (Gitea) + - Self-hosted Gitea instance + - Uses Gitea Actions for CI/CD automation + +3. **No Structural Changes Needed**: + - Directory structure remains the same + - Workflow files will work as-is + - Only documentation references needed updating + +## Files Modified + +1. `.cursorrules` - Updated 3 references from GitHub to Gitea +2. `docs/AGENT-GUIDELINES.md` - Updated 6 references and added compatibility notes + +## Next Steps + +When creating workflows in Phase 3: +- Use standard GitHub Actions YAML format +- Workflows will work with Gitea Actions automatically +- Reference "Gitea Actions" in documentation, but note GitHub Actions compatibility +- Test workflows in Gitea Actions interface (similar to GitHub Actions tab) + +--- + +**Location**: `docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md` +**Related**: Phase 0 setup, Gitea Actions compatibility + diff --git a/docs/PHASE-UPDATES/README.md b/docs/PHASE-UPDATES/README.md new file mode 100644 index 0000000..3db05a0 --- /dev/null +++ b/docs/PHASE-UPDATES/README.md @@ -0,0 +1,59 @@ +# Phase Updates Documentation + +**Purpose**: This directory contains documentation related to phase updates, system replication guides, and migration notes. + +**Last Updated**: 2025-01-27 + +--- + +## Contents + +### System Replication + +- **[COMPLETE-SYSTEM-REPLICATION-GUIDE.md](./COMPLETE-SYSTEM-REPLICATION-GUIDE.md)** - Comprehensive guide for replicating the PAIRS documentation and automation system in another project. Includes all structures, schemas, templates, rationale, and step-by-step instructions. + +### Phase Updates + +- **[PHASE-0-GITEA-UPDATES.md](./PHASE-0-GITEA-UPDATES.md)** - Documents updates made to Phase 0 files to reflect Gitea (self-hosted) instead of GitHub. Includes changes to `.cursorrules` and `docs/AGENT-GUIDELINES.md`. + +--- + +## Purpose + +This directory serves as a reference for: + +1. **System Replication**: Complete guide for setting up the documentation and automation system in new projects +2. **Phase Updates**: Tracking changes and updates made during each phase of project setup +3. **Migration Notes**: Documenting platform-specific adaptations (e.g., Gitea vs GitHub) + +--- + +## Usage + +### For System Replication + +If you want to replicate this documentation system in another project: +1. Read `COMPLETE-SYSTEM-REPLICATION-GUIDE.md` +2. Follow the step-by-step replication guide +3. Customize for your project's needs + +### For Phase Updates + +When making updates during phase setup: +1. Document changes in phase-specific update files +2. Reference these files when reviewing phase work +3. Use as historical record of decisions made + +--- + +## Related Documentation + +- **Agent Guidelines**: `docs/AGENT-GUIDELINES.md` - Guidelines for AI agents +- **Gitea Documentation**: `docs/GITEA/` - Gitea-specific documentation +- **Phase Documentation**: `tendril/phases/` - Phase blueprints and related docs + +--- + +**Location**: `docs/PHASE-UPDATES/` +**Maintained by**: Tendril Project Maintainers +