Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(phases): add Phase 3-6 plans and update Phase 2 plan

Browse Source 
This commit adds comprehensive plan documents for all remaining phases
of the project setup system replication:

## Phase Plans Added

### Phase 2 Plan (Updated)
- KB System Setup plan document
- Already implemented in previous commit
- Plan document now tracked in repository

### Phase 3 Plan (New)
- Gitea Actions Workflows Setup
- Covers .github/ documentation and workflow creation
- KB lint and KB index update workflows
- Customized for Tendril and Gitea platform

### Phase 4 Plan (New)
- LLM Usage Guides Setup
- LLM-Usage-Guide.md and Prompt-Creation-Guide.md
- Initial prompt documents
- Customized for Tendril project

### Phase 5 Plan (New)
- Validation and Testing
- Comprehensive testing procedures
- Test scenarios for all system components
- Troubleshooting guide

### Phase 6 Plan (New)
- Customization and Final Verification
- Project name and terminology verification
- Directory structure verification
- Final documentation review
- System integration verification

## Plan Structure

All plans follow consistent structure:
- Overview and current state
- Detailed task breakdown
- Customizations for Tendril
- Files to create
- Dependencies and success criteria
- Validation checklists
- Notes and references

## Customizations

All plans are customized for:
- Tendril project (not "pairs")
- Gitea platform (not GitHub)
- Tendril-specific directory structure
- Gitea Actions (with GitHub Actions compatibility notes)

## Files Added

- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-2-PLAN.md (5.0KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-3-PLAN.md (13KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md (8.1KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-5-PLAN.md (12KB)
- kb/_guides/PROJECT-SETUP-GUIDE/PHASE-6-PLAN.md (11KB)

Total: 5 phase plan documents, ~49KB of planning documentation
This commit is contained in:
Data Warrior
2025-11-11 11:50:01 -07:00
parent aecc370e1d
commit db003786f9
5 changed files with 1532 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
kb/_guides/PROJECT-SETUP-GUIDE/PHASE-2-PLAN.md Normal file
View File

@@ -0,0 +1,143 @@
# Gitea Documentation Integration and GitHub Reference Cleanup
## Objective
Update `.cursorrules` and related documentation to:
1. Add references to Gitea documentation (`docs/GITEA/`)
2. Ensure all platform references correctly use "Gitea" (not "GitHub")
3. Add guidance to consult Gitea documentation when working with Gitea-specific features
4. Verify all compatibility notes are clear (Gitea Actions is compatible with GitHub Actions format)
## Current State Analysis
### .cursorrules File
- ✅ Already uses "Gitea Actions" (correct)
- ✅ References `.github/` directory (correct - that's the actual directory name)
- ❌ Missing: References to Gitea documentation
- ❌ Missing: Guidance to consult Gitea docs when working with workflows
- ❌ Missing: Reference to repository URL (https://git.parkingmeter.info/Mycelium/tendril)
### Documentation Files
- ✅ `docs/GITEA/` - Comprehensive Gitea documentation exists
- ✅ Most references correctly note "compatible with GitHub Actions"
- ⚠️ Some references may need clarification
- ✅ `docs/AGENT-GUIDELINES.md` - Already updated for Gitea
## Tasks
### Task 1: Update .cursorrules with Gitea Documentation References
**Location**: `.cursorrules`
**Changes Needed**:
1. Add section referencing Gitea documentation:
- Reference `docs/GITEA/` for Gitea-specific guidance
- Reference `docs/GITEA/LLM-Gitea-Guidelines.md` for LLM-specific guidelines
- Reference `docs/GITEA/Gitea-Actions-Guide.md` when working with workflows
2. Add repository context:
- Repository: https://git.parkingmeter.info/Mycelium/tendril
- Platform: Gitea (self-hosted)
3. Update General Project Rules section:
- Add reference to Gitea documentation
- Note to consult Gitea docs for platform-specific questions
4. Update workflow maintenance rules:
- Reference `docs/GITEA/Gitea-Actions-Guide.md`
- Note Gitea Actions compatibility
### Task 2: Review and Update Other Documentation Files
**Files to Check**:
- `docs/AGENT-GUIDELINES.md` - Verify Gitea references are correct
- `docs/PHASE-UPDATES/README.md` - Check for any GitHub references
- `PHASE-1-PLAN.md` - Update if needed
**Action**: Ensure all references correctly use "Gitea" terminology and link to Gitea documentation where appropriate.
### Task 3: Add Gitea Platform Context Section
**Location**: `.cursorrules` (new section)
**Content**:
- Repository URL and platform information
- Reference to Gitea documentation
- Note about Gitea Actions compatibility
- Guidance on when to consult Gitea docs
## Implementation Details
### .cursorrules Updates
**Add new section after "General Project Rules"**:
```markdown
## Gitea Platform Context
**Repository**: https://git.parkingmeter.info/Mycelium/tendril
**Platform**: Gitea (self-hosted)
**Actions System**: Gitea Actions (compatible with GitHub Actions format)
### Gitea Documentation References
When working with Gitea-specific features, workflows, or platform questions:
1. **Consult Gitea Documentation**: See `docs/GITEA/` for comprehensive Gitea guidance
2. **LLM Guidelines**: See `docs/GITEA/LLM-Gitea-Guidelines.md` for LLM-specific guidelines
3. **Actions Guide**: See `docs/GITEA/Gitea-Actions-Guide.md` when working with workflows
4. **API Reference**: See `docs/GITEA/Gitea-API-Reference.md` for API differences
### Platform Terminology
- Use **"Gitea"** (not "GitHub") when referring to the platform
- Use **"Gitea Actions"** (not "GitHub Actions") but note compatibility
- Use **"Gitea issues"** (not "GitHub issues")
- Use **"Gitea repository"** (not "GitHub repository")
- Note: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure
```
**Update "General Project Rules" section**:
- Add: "Consult `docs/GITEA/` documentation for Gitea-specific guidance"
**Update workflow maintenance rules**:
- Add reference to `docs/GITEA/Gitea-Actions-Guide.md`
- Note to consult Gitea Actions guide for workflow questions
## Verification Checklist
After updates:
- [ ] `.cursorrules` references Gitea documentation
- [ ] `.cursorrules` includes repository URL
- [ ] `.cursorrules` includes platform context section
- [ ] All "GitHub" references are either:
- Updated to "Gitea" (when referring to platform)
- Left as-is with compatibility note (when referring to GitHub Actions compatibility)
- [ ] All documentation files reviewed
- [ ] Links to Gitea documentation are correct
- [ ] Terminology is consistent throughout
## Files to Modify
1. `.cursorrules` - Add Gitea platform context and documentation references
2. Review other docs for any missed GitHub references (if found, update)
## Expected Outcome
- `.cursorrules` properly references Gitea platform and documentation
- Clear guidance on when to consult Gitea documentation
- Consistent terminology throughout (Gitea, not GitHub)
- Proper compatibility notes where GitHub Actions format is referenced

384
kb/_guides/PROJECT-SETUP-GUIDE/PHASE-3-PLAN.md Normal file
View File

@@ -0,0 +1,384 @@
# Phase 3: Gitea Actions Workflows Setup - Detailed Plan
**Objective**: Configure Gitea Actions workflows and automation documentation for repository maintenance
**Status**: Ready for Review
**Date**: 2025-01-27
---
## Overview
Phase 3 establishes Gitea Actions workflows and automation documentation for the Tendril repository. This includes KB validation workflows, index auto-update automation, and comprehensive documentation for maintaining the `.github/` directory structure.
**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure.
---
## Current State
- `.github/workflows/` directory exists (empty)
- Phase 2 KB System Setup completed (KB files, templates, scripts ready)
- KB index generation script exists: `kb/scripts/generate-index.sh`
- KB validation rules defined in replication guide
- Missing: `.github/` documentation files and workflow files
---
## Tasks Breakdown
### Task 1: Create .github/README.md
**File**: `.github/README.md`
Create comprehensive overview of `.github/` directory including:
- Purpose and structure of `.github/` directory
- Workflows overview (kb-lint, kb-index-update)
- Documentation files explanation
- Maintenance guidelines
- Workflow update procedures
**Source**: Template from `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md` (GitHub Automation System section, lines 1044-1110)
**Customizations**:
- Replace "GitHub Actions" with "Gitea Actions" (with compatibility note)
- Replace "GitHub" with "Gitea" where referring to platform
- Update repository name to "tendril"
- Note Gitea Actions compatibility with GitHub Actions format
---
### Task 2: Create .github/CHANGELOG.md
**File**: `.github/CHANGELOG.md`
Create changelog for tracking workflow and automation changes:
- Initial entry documenting Phase 3 setup
- Date-based format: `## [YYYY-MM-DD] Brief Description`
- Sections: Added, Changed, Fixed, Notes
- Format: `- **\`[file-path]\`** - [Description]`
**Source**: Template from `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md` (lines 1112-1140)
**Initial Entry**:
```markdown
## [2025-01-27] Gitea Actions Workflows Setup
### Added
- **`.github/README.md`** - .github directory overview
- **`.github/CHANGELOG.md`** - Workflow change tracking (this file)
- **`.github/decisions.md`** - Automation decisions
- **`.github/LLM-Usage-Guide--tendril.md`** - LLM instructions for workflows
- **`.github/workflows/kb-lint.yml`** - KB file validation workflow
- **`.github/workflows/kb-index-update.yml`** - KB index auto-update workflow
### Notes
- Phase 3 Gitea Actions Workflows Setup completed
- All workflows use Gitea Actions (compatible with GitHub Actions format)
- Workflows configured for Tendril repository structure
```
---
### Task 3: Create .github/decisions.md
**File**: `.github/decisions.md`
Create decisions document for automation choices:
- Purpose statement
- Decision format explanation
- Initial decisions about workflow setup
- Future decisions section
**Source**: Template from `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md` (lines 1142-1197)
**Initial Decisions to Document**:
1. **Use Gitea Actions (not GitHub Actions)**
- Context: Repository is on Gitea platform
- Decision: Use Gitea Actions with GitHub Actions compatibility
- Rationale: Gitea Actions uses same YAML format, seamless migration
- Impact: All workflows use `.github/workflows/` structure
2. **Automate KB Index Updates**
- Context: KB index must stay current with KB files
- Decision: Auto-update index on push to main when KB files change
- Rationale: Reduces manual maintenance, ensures index accuracy
- Impact: Index always reflects current KB state
3. **Validate KB Files in CI**
- Context: KB files must follow strict naming and frontmatter rules
- Decision: Validate KB files on push and pull requests
- Rationale: Catch errors early, maintain KB system integrity
- Impact: Invalid KB files block commits
---
### Task 4: Create .github/LLM-Usage-Guide--tendril.md
**File**: `.github/LLM-Usage-Guide--tendril.md`
Create LLM instructions for working with workflows:
- Repository context (Tendril, Gitea platform)
- Understanding .github directory structure
- Working with workflows (modifying, adding, removing)
- Workflow-specific instructions (kb-lint, kb-index-update)
- Documentation maintenance procedures
- Common tasks and validation checklist
**Source**: Template from `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md` (lines 1199-1378)
**Customizations**:
- Replace `{REPO-NAME}` with "tendril"
- Replace "GitHub Actions" with "Gitea Actions" (with compatibility note)
- Update repository URL: https://git.parkingmeter.info/Mycelium/tendril
- Add workflow-specific instructions for kb-lint and kb-index-update
- Reference `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance
---
### Task 5: Create KB Lint Workflow
**File**: `.github/workflows/kb-lint.yml`
Create workflow to validate KB files:
**Purpose**: Validates KB file naming, frontmatter, and structure on push and pull requests
**Triggers**:
- Push to any branch when `kb/**/*.md` files change
- Pull requests when `kb/**/*.md` files change
**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 must exist and be valid YAML
- 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/`
**Source**: Validation script from `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md` (lines 1561-1620)
**Workflow Structure**:
```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 here
```
**Implementation Notes**:
- Use bash script inline or create separate validation script
- Exclude `_guides/`, `_templates/`, `README.md`, `_index.md`, `CHANGELOG.md` from validation
- Provide clear error messages for each validation failure
- Exit with error code if any validation fails
---
### Task 6: Create KB Index Update Workflow
**File**: `.github/workflows/kb-index-update.yml`
Create workflow to auto-update KB index:
**Purpose**: Automatically regenerates `kb/_index.md` when KB files change on main branch
**Triggers**:
- Push to `main` branch when `kb/**/*.md` files change
- Exclude `_guides/`, `_templates/`, `README.md`, `_index.md`, `CHANGELOG.md`
**Workflow Steps**:
1. Checkout repository
2. Run `kb/scripts/generate-index.sh`
3. Check if `kb/_index.md` changed
4. If changed, commit and push update
5. Use appropriate git user (Gitea Actions)
**Source**: Template from `docs/GITEA/Gitea-Actions-Guide.md` (lines 224-249) and replication guide
**Workflow Structure**:
```yaml
name: Update KB Index
on:
push:
branches: [ main ]
paths:
- 'kb/**/*.md'
permissions:
contents: write
jobs:
update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
token: ${{ secrets.GITHUB_TOKEN }}
- 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
```
**Implementation Notes**:
- Requires `contents: write` permission to push changes
- Use `|| exit 0` to handle case where index hasn't changed
- Ensure script is executable (already done in Phase 2)
- Test that script works in Gitea Actions environment
---
## Customizations for Tendril
### Platform References
- **Use**: "Gitea Actions" (not "GitHub Actions") but note compatibility
- **Note**: Gitea Actions is compatible with GitHub Actions format
- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
- **Platform**: Gitea (self-hosted)
### Repository Name
- **Use**: "tendril" (not "pairs" or placeholder)
- **LLM Guide**: `LLM-Usage-Guide--tendril.md`
### Workflow Customizations
- **KB paths**: `kb/**/*.md` (matches Tendril structure)
- **Index script**: `./kb/scripts/generate-index.sh` (relative to repo root)
- **Main branch**: Use `main` (verify actual branch name)
### Documentation References
- Reference `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance
- Reference `docs/GITEA/LLM-Gitea-Guidelines.md` for LLM guidelines
- Note compatibility with GitHub Actions format
---
## Files to Create
1. **`.github/README.md`** - .github directory overview
2. **`.github/CHANGELOG.md`** - Workflow change tracking
3. **`.github/decisions.md`** - Automation decisions
4. **`.github/LLM-Usage-Guide--tendril.md`** - LLM instructions
5. **`.github/workflows/kb-lint.yml`** - KB validation workflow
6. **`.github/workflows/kb-index-update.yml`** - KB index auto-update workflow
---
## Dependencies
- Phase 0: Directory structure (completed)
- Phase 1: Phase documentation templates (completed)
- Phase 2: KB System Setup (completed)
- KB templates and scripts must exist
- Index generation script must be executable
- KB validation rules must be defined
---
## Success Criteria
- All `.github/` documentation files created and properly formatted
- Both workflows created and use correct YAML syntax
- KB lint workflow validates all KB file rules
- KB index update workflow successfully regenerates index
- All files customized for Tendril project and Gitea platform
- Documentation references Gitea Actions (with compatibility notes)
- Workflows tested and functional
---
## Validation Checklist
Before completing Phase 3, verify:
- [ ] `.github/README.md` exists and documents all workflows
- [ ] `.github/CHANGELOG.md` exists with initial Phase 3 entry
- [ ] `.github/decisions.md` exists with initial decisions
- [ ] `.github/LLM-Usage-Guide--tendril.md` exists and is complete
- [ ] `.github/workflows/kb-lint.yml` exists and validates KB files
- [ ] `.github/workflows/kb-index-update.yml` exists and updates index
- [ ] All files use "Gitea Actions" terminology (with compatibility notes)
- [ ] All files reference "tendril" (not "pairs")
- [ ] Workflows use correct paths for Tendril structure
- [ ] Documentation references Gitea documentation where appropriate
- [ ] Workflows can be tested (syntax validation, dry-run if possible)
---
## Testing Workflows
### Test KB Lint Workflow
1. Create a test KB file with invalid filename
2. Push to branch
3. Verify workflow runs and fails validation
4. Fix filename
5. Verify workflow passes
### Test KB Index Update Workflow
1. Create a test KB file with valid frontmatter
2. Push to main branch
3. Verify workflow runs
4. Check that `kb/_index.md` is updated
5. Verify commit is created with update
**Note**: Testing may require Gitea Actions runners to be configured. Consult `docs/GITEA/Gitea-Actions-Guide.md` for runner setup.
---
## Next Steps After Phase 3
Once Phase 3 is complete:
- Phase 4: LLM Usage Guides
- Phase 5: Documentation Migration
- Phase 6: Validation and Testing
---
## Notes
- Gitea Actions uses same YAML format as GitHub Actions, so workflows are compatible
- Workflows must be tested once Gitea Actions runners are configured
- KB validation rules match those defined in Phase 2 KB System Setup
- Index update workflow requires write permissions to push changes
- All workflows should reference Gitea Actions (not GitHub Actions) in documentation
- Consult `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific workflow guidance
---
**Location**: `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-3-PLAN.md`
**Related**:
- `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
- `docs/GITEA/Gitea-Actions-Guide.md`
- `docs/GITEA/LLM-Gitea-Guidelines.md`
- `kb/README.md` (KB system documentation)

257
kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md Normal file
View File

@@ -0,0 +1,257 @@
# Phase 4: LLM Usage Guides Setup - Detailed Plan
**Objective**: Create LLM Usage Guides and prompt documentation system for AI-assisted workflows
**Status**: Ready for Review
**Date**: 2025-01-27
---
## Overview
Phase 4 establishes the LLM Usage Guides system, which provides reusable prompt documents for AI assistants to perform specific tasks. These guides enable drag-and-drop workflows in Cursor chat and standardize common operations.
---
## Current State
- `docs/PROMPTS/` directory exists (created in Phase 0)
- Phase documentation system established (Phase 1)
- KB system established (Phase 2)
- Gitea Actions workflows established (Phase 3)
- Missing: LLM Usage Guide, Prompt Creation Guide, initial prompt documents
---
## Tasks Breakdown
### Task 1: Create LLM Usage Guide
**File**: `docs/PROMPTS/LLM-Usage-Guide.md`
Create comprehensive guide for LLMs on how to recognize, interpret, and execute prompt documents:
**Purpose**: Instructions for AI assistants on working with prompt documents
**Key Sections**:
- Recognizing Prompt Documents
- Executing Prompts (Phase-by-Phase Execution)
- Information Gathering
- Error Handling
- Validation Steps
- Providing Feedback
- Best Practices
- Special Instructions
- Troubleshooting
**Source**: Template from `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md` (LLM Usage Guides section, lines 1510-1524)
**Content Structure**:
- How to identify prompt documents (naming convention, structure)
- Step-by-step execution process
- Information gathering requirements
- Error handling procedures
- Validation checklists
- Feedback mechanisms
- Best practices for prompt execution
**Customizations**:
- Reference Tendril project structure
- Use Gitea terminology (not GitHub)
- Reference Tendril-specific paths and conventions
---
### Task 2: Create Prompt Creation Guide
**File**: `docs/PROMPTS/Prompt-Creation-Guide.md`
Create guide for creating effective, reusable prompt documents:
**Purpose**: Guide for creating effective, reusable prompt documents
**Key Sections**:
- Naming Convention (`NN-Descriptive-Name-Prompt.md`)
- 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
**Source**: Template from `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md` (LLM Usage Guides section, lines 1526-1540)
**Content Structure**:
- Naming convention explanation (zero-padded numbers)
- Complete prompt template structure
- Best practices for clarity and effectiveness
- Writing guidelines for instructions
- Testing procedures
- Common patterns and examples
- Decision criteria for new prompts
- Update procedures
- Validation checklist
**Customizations**:
- Examples relevant to Tendril project
- Reference Tendril-specific workflows
- Use Gitea terminology
---
### Task 3: Create Initial Prompt Documents
**Files**: Create at least one initial prompt document to demonstrate the system
**Naming Convention**: `NN-Descriptive-Name-Prompt.md` where NN is zero-padded two-digit number (00, 01, 02, etc.)
**Suggested Initial Prompts**:
1. **`00-Project-Status-Check-Prompt.md`**
- Purpose: Check current project status across all phases
- Use case: Quick status overview before starting work
- Steps: Read phase blueprints, check tasks, summarize status
2. **`01-KB-Content-Search-Prompt.md`**
- Purpose: Search KB system for relevant content
- Use case: Find existing knowledge before creating new KB entries
- Steps: Read KB index, search by topic/tag/phase, summarize findings
3. **`02-Phase-Documentation-Sync-Prompt.md`**
- Purpose: Ensure phase documentation is synchronized
- Use case: After editing blueprint, verify all related docs are updated
- Steps: Check blueprint, tasks, decisions, changelog for consistency
**Prompt Structure** (from template):
- Purpose statement
- How to use instructions
- CRITICAL: Information Gathering section
- Step-by-Step Process
- Error Handling
- Validation Checklist
- Important Notes for AI Assistant
**Source**: Template from `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md` (Prompt Document Template, lines 1429-1508)
---
## Customizations for Tendril
### Directory Structure
- **Use**: `docs/PROMPTS/` (already exists)
- **Reason**: Matches project structure
### Platform References
- **Use**: "Gitea" (not "GitHub")
- **Reference**: Gitea-specific workflows and features
- **Note**: Gitea Actions compatibility where relevant
### Project Context
- **Project Name**: Tendril
- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
- **Phase Structure**: `tendril/phases/phase-XX-name/`
- **KB Structure**: `kb/` with category directories
### Prompt Examples
- Reference Tendril-specific workflows
- Use Tendril project structure in examples
- Include Gitea-specific operations where relevant
---
## Files to Create
1. **`docs/PROMPTS/LLM-Usage-Guide.md`** - LLM instructions for prompt execution
2. **`docs/PROMPTS/Prompt-Creation-Guide.md`** - Guide for creating prompts
3. **`docs/PROMPTS/00-Project-Status-Check-Prompt.md`** - Initial prompt (optional but recommended)
4. **`docs/PROMPTS/01-KB-Content-Search-Prompt.md`** - Initial prompt (optional but recommended)
5. **`docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md`** - Initial prompt (optional but recommended)
**Note**: At minimum, create the two guide files. Initial prompt documents are recommended but optional.
---
## Dependencies
- Phase 0: Directory structure (completed)
- Phase 1: Phase documentation system (completed)
- Phase 2: KB System Setup (completed)
- Phase 3: Gitea Actions Workflows (completed)
- `docs/PROMPTS/` directory exists
---
## Success Criteria
- LLM Usage Guide created and comprehensive
- Prompt Creation Guide created with complete template
- At least one initial prompt document created (recommended)
- All files customized for Tendril project
- Documentation references Gitea (not GitHub)
- Prompts follow naming convention
- Prompts include all required sections
---
## Validation Checklist
Before completing Phase 4, verify:
- [ ] `docs/PROMPTS/LLM-Usage-Guide.md` exists and is complete
- [ ] `docs/PROMPTS/Prompt-Creation-Guide.md` exists and is complete
- [ ] At least one initial prompt document created (recommended)
- [ ] All prompts follow naming convention: `NN-Descriptive-Name-Prompt.md`
- [ ] All prompts include required sections (Purpose, How to Use, Information Gathering, Steps, Validation)
- [ ] All files reference "Tendril" (not "pairs")
- [ ] All files use "Gitea" terminology (not "GitHub")
- [ ] Examples are relevant to Tendril project structure
- [ ] Documentation is clear and actionable
---
## Testing Prompts
### Test LLM Usage Guide
1. Open a prompt document in Cursor
2. Verify LLM recognizes it as a prompt document
3. Test execution of a simple prompt
4. Verify LLM follows instructions correctly
### Test Prompt Creation Guide
1. Create a new prompt using the guide
2. Verify it follows naming convention
3. Verify it includes all required sections
4. Test the prompt with an LLM
5. Verify it accomplishes intended task
---
## Next Steps After Phase 4
Once Phase 4 is complete:
- Phase 5: Validation and Testing
- Phase 6: Customization and Final Verification
---
## Notes
- LLM Usage Guides enable reusable, standardized workflows
- Prompts should be tested with actual LLM execution
- Prompt documents are designed for drag-and-drop use in Cursor
- Initial prompts serve as examples and useful tools
- All prompts should be customized for Tendril project context
- Consult `docs/GITEA/LLM-Gitea-Guidelines.md` for Gitea-specific LLM guidance
---
**Location**: `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md`
**Related**:
- `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
- `docs/GITEA/LLM-Gitea-Guidelines.md`
- `docs/PROMPTS/` directory

381
kb/_guides/PROJECT-SETUP-GUIDE/PHASE-5-PLAN.md Normal file
View File

@@ -0,0 +1,381 @@
# Phase 5: Validation and Testing - Detailed Plan
**Objective**: Comprehensive testing and validation of all system components
**Status**: Ready for Review
**Date**: 2025-01-27
---
## Overview
Phase 5 validates that all components of the documentation and automation system work correctly together. This includes testing Cursor rules, KB system, phase documentation synchronization, Gitea Actions workflows, and LLM prompts.
---
## Current State
- Phase 0: Foundation & Cursor Rules (completed)
- Phase 1: Phase Documentation System (completed)
- Phase 2: KB System Setup (completed)
- Phase 3: Gitea Actions Workflows (completed)
- Phase 4: LLM Usage Guides (completed)
- All components need validation and testing
---
## Tasks Breakdown
### Task 1: Test Cursor Rules
**Objective**: Verify Cursor rules are loaded and functioning correctly
**Steps**:
1. **Verify Rules are Loaded**:
- Open project in Cursor
- Check Cursor settings → Rules, Memories, Commands → Project Rules
- Verify `.cursorrules` file is recognized
- Check that rules appear in Cursor interface
2. **Test Phase Documentation Synchronization**:
- Edit a `blueprint.md` file in any phase
- Make a change (e.g., update status, add deliverable)
- Verify that LLM checks related documents:
- `changelog.md` is updated
- `tasks.md` is checked/updated
- `decisions.md` is reviewed
- Verify consistency across all documents
3. **Test KB System Rules**:
- Create a test KB file
- Verify LLM follows KB naming convention
- Verify LLM includes all required frontmatter
- Verify LLM updates index and changelog
4. **Test Workflow Maintenance Rules**:
- Modify a workflow file
- Verify LLM updates `.github/CHANGELOG.md`
- Verify LLM updates `.github/decisions.md` if decision-related
- Verify LLM updates `.github/README.md` if needed
**Success Criteria**:
- Cursor rules are loaded and visible
- Phase documentation synchronization works
- KB system rules are followed
- Workflow maintenance rules are followed
---
### Task 2: Test KB System
**Objective**: Verify KB system functions correctly end-to-end
**Steps**:
1. **Create Test KB File**:
- Create a test KB file with valid frontmatter
- Use proper naming: `YYYY-MM-DD--test-kb-file--note.md`
- Include all 18 required fields
- Place in appropriate category
2. **Test Index Generation**:
- Run: `kb/scripts/generate-index.sh`
- Verify script completes successfully
- Check that `kb/_index.md` is updated
- Verify new file appears in index:
- File listing by category
- Topics index (if topics provided)
- Tags index (if tags provided)
- Phase relevance index (if phases provided)
3. **Test KB Lint Workflow** (if Phase 3 completed):
- Push test KB file to branch
- Verify `kb-lint.yml` workflow runs
- Verify validation passes for valid file
- Create invalid file (wrong filename pattern)
- Verify workflow fails with appropriate error
4. **Test KB Index Update Workflow** (if Phase 3 completed):
- Push valid KB file to main branch
- Verify `kb-index-update.yml` workflow runs
- Verify `kb/_index.md` is updated automatically
- Verify commit is created with update
5. **Test KB Changelog Update**:
- Verify changelog entry is created
- Verify format is correct
- Verify date and description are accurate
**Success Criteria**:
- KB files can be created with proper format
- Index generation script works correctly
- Index reflects all KB files accurately
- KB lint workflow validates files correctly
- KB index update workflow auto-updates index
- Changelog updates work correctly
---
### Task 3: Test Phase Documentation
**Objective**: Verify phase documentation synchronization works
**Steps**:
1. **Test Blueprint Modification**:
- Edit a `blueprint.md` file
- Change status, add deliverable, or modify milestone
- Verify LLM checks related documents:
- Reads `changelog.md`
- Reads `tasks.md`
- Reads `decisions.md`
- Verify LLM updates documents appropriately
2. **Test Synchronization Rules**:
- Make change to blueprint status
- Verify `tasks.md` status is updated
- Verify `changelog.md` has new entry
- Verify project name consistency
3. **Test README Maintenance**:
- Make significant phase change
- Verify LLM checks `README.md`
- Verify `README.md` is updated if needed
- Verify phase statuses are accurate
4. **Test Cross-Document Consistency**:
- Verify project name matches across all documents
- Verify dates are consistent
- Verify status indicators are aligned
- Verify phase names match
**Success Criteria**:
- Blueprint modifications trigger synchronization checks
- Related documents are updated appropriately
- README is checked and updated when needed
- All documents remain consistent
---
### Task 4: Test Gitea Actions Workflows
**Objective**: Verify Gitea Actions workflows function correctly
**Steps**:
1. **Test KB Lint Workflow**:
- Create valid KB file
- Push to branch
- Verify workflow runs
- Verify validation passes
- Create invalid KB file
- Verify workflow fails with clear error
2. **Test KB Index Update Workflow**:
- Create valid KB file
- Push to main branch
- Verify workflow runs
- Verify index is updated
- Verify commit is created
- Verify commit message is correct
3. **Test Workflow Triggers**:
- Verify workflows trigger on correct paths
- Verify workflows trigger on correct events
- Test with `workflow_dispatch` if available
4. **Test Workflow Permissions**:
- Verify read permissions work for lint workflow
- Verify write permissions work for index update workflow
- Check workflow logs for errors
5. **Test Workflow Documentation**:
- Verify workflow changes update `.github/CHANGELOG.md`
- Verify workflow changes update `.github/decisions.md` if needed
- Verify workflow changes update `.github/README.md` if needed
**Success Criteria**:
- KB lint workflow validates files correctly
- KB index update workflow updates index automatically
- Workflows trigger on correct events
- Workflow permissions are correct
- Workflow documentation is maintained
**Note**: Testing workflows requires Gitea Actions runners to be configured. Consult `docs/GITEA/Gitea-Actions-Guide.md` for runner setup.
---
### Task 5: Test LLM Prompts
**Objective**: Verify LLM prompt documents work correctly
**Steps**:
1. **Test Prompt Recognition**:
- Open a prompt document in Cursor
- Verify LLM recognizes it as a prompt document
- Verify LLM understands structure
2. **Test Prompt Execution**:
- Execute a simple prompt (e.g., Project Status Check)
- Verify LLM follows instructions
- Verify LLM gathers required information
- Verify LLM completes steps correctly
3. **Test Information Gathering**:
- Use prompt that requires information
- Verify LLM asks for missing information
- Verify LLM doesn't make assumptions
4. **Test Validation Checklist**:
- Execute prompt with validation checklist
- Verify LLM checks all items
- Verify LLM reports validation results
5. **Test Error Handling**:
- Test prompt with error condition
- Verify LLM handles error appropriately
- Verify LLM provides helpful error messages
**Success Criteria**:
- Prompts are recognized by LLM
- Prompts execute correctly
- Information gathering works
- Validation checklists are followed
- Error handling works appropriately
---
## Comprehensive Test Scenarios
### Scenario 1: Complete KB Workflow
1. Create KB file with LLM assistance
2. Verify file follows naming convention
3. Verify frontmatter is complete
4. Verify file is routed correctly
5. Run index generation script
6. Verify index is updated
7. Update changelog
8. Commit all changes together
9. Push to branch
10. Verify KB lint workflow runs and passes
11. Merge to main
12. Verify KB index update workflow runs
13. Verify index is updated automatically
### Scenario 2: Phase Documentation Update
1. Edit phase blueprint
2. Verify LLM checks related documents
3. Verify changelog is updated
4. Verify tasks are synced
5. Verify decisions are reviewed
6. Verify README is checked
7. Commit changes
8. Verify all documents are consistent
### Scenario 3: Workflow Modification
1. Modify a workflow file
2. Verify LLM updates `.github/CHANGELOG.md`
3. Verify LLM updates `.github/decisions.md` if needed
4. Verify LLM updates `.github/README.md` if needed
5. Test workflow with `workflow_dispatch` if available
6. Verify workflow runs successfully
7. Commit changes
---
## Validation Checklist
Before completing Phase 5, verify:
- [ ] Cursor rules are loaded and functioning
- [ ] Phase documentation synchronization works
- [ ] KB system functions end-to-end
- [ ] KB index generation works correctly
- [ ] KB lint workflow validates files
- [ ] KB index update workflow auto-updates index
- [ ] Phase documentation stays synchronized
- [ ] README maintenance works
- [ ] Gitea Actions workflows function correctly
- [ ] LLM prompts execute correctly
- [ ] All test scenarios pass
- [ ] Documentation is accurate and up-to-date
---
## Troubleshooting
### Common Issues
**Cursor Rules Not Working**:
- Verify `.cursorrules` file exists
- Check Cursor settings
- Restart Cursor
- Verify file paths in rules
**KB Validation Failures**:
- Check filename pattern
- Verify all frontmatter fields present
- Check date/type match filename
- Verify routing confidence is valid
**Workflow Not Running**:
- Check Gitea Actions runners are configured
- Verify workflow syntax is valid
- Check workflow triggers
- Review workflow logs
**Phase Docs Out of Sync**:
- Manually review all documents
- Update changelog with discrepancies
- Sync tasks with blueprint
- Verify project name consistency
**LLM Prompt Not Working**:
- Verify prompt structure is complete
- Check all required sections present
- Test with simple task first
- Review LLM-Usage-Guide.md
---
## Success Criteria
- All components tested and validated
- All workflows function correctly
- All synchronization rules work
- All documentation is accurate
- All test scenarios pass
- System is ready for production use
---
## Next Steps After Phase 5
Once Phase 5 is complete:
- Phase 6: Customization and Final Verification (if needed)
- System is ready for ongoing use
---
## Notes
- Testing should be thorough but practical
- Focus on critical paths and common workflows
- Document any issues found during testing
- Fix issues before marking phase complete
- Some tests may require Gitea Actions runners to be configured
- Consult `docs/GITEA/Gitea-Actions-Guide.md` for workflow testing guidance
---
**Location**: `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-5-PLAN.md`
**Related**:
- `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
- `docs/GITEA/Gitea-Actions-Guide.md`
- All previous phase plans

367
kb/_guides/PROJECT-SETUP-GUIDE/PHASE-6-PLAN.md Normal file
View File

@@ -0,0 +1,367 @@
# Phase 6: Customization and Final Verification - Detailed Plan
**Objective**: Final customization pass and comprehensive verification of entire system
**Status**: Ready for Review
**Date**: 2025-01-27
---
## Overview
Phase 6 performs a final pass to ensure all customization for Tendril is complete, verifies consistency across all documentation, and confirms the system is ready for ongoing use. Most customization has been done incrementally in previous phases, but this phase ensures nothing was missed.
---
## Current State
- Phase 0: Foundation & Cursor Rules (completed)
- Phase 1: Phase Documentation System (completed)
- Phase 2: KB System Setup (completed)
- Phase 3: Gitea Actions Workflows (completed)
- Phase 4: LLM Usage Guides (completed)
- Phase 5: Validation and Testing (completed)
- Final verification and cleanup needed
---
## Tasks Breakdown
### Task 1: Project Name Customization Verification
**Objective**: Verify all references use "Tendril" (not "pairs" or placeholders)
**Steps**:
1. **Search for Placeholder Names**:
- Search codebase for "pairs" (case-insensitive)
- Search for "PAIRS" (all caps)
- Search for common placeholders: "{REPO-NAME}", "{PROJECT-NAME}", etc.
- Document any found instances
2. **Verify Project Name Consistency**:
- Check all phase blueprints use "Tendril"
- Check all KB files use `project: ["tendril"]`
- Check all documentation uses "Tendril"
- Check all templates use "tendril"
3. **Update Any Remaining References**:
- Replace any found placeholders
- Update any missed "pairs" references
- Ensure consistency across all files
**Files to Check**:
- `.cursorrules`
- `docs/AGENT-GUIDELINES.md`
- `kb/README.md`
- `kb/_templates/*.md`
- `kb/_guides/KB_INGEST_PROMPT.md`
- `.github/README.md`
- `.github/LLM-Usage-Guide--tendril.md`
- `docs/PROMPTS/*.md`
- All phase documentation files
**Success Criteria**:
- No "pairs" references found (except in historical context)
- No placeholder names found
- All files use "Tendril" or "tendril" consistently
---
### Task 2: Directory Structure Verification
**Objective**: Verify all directory references match Tendril structure
**Steps**:
1. **Verify Phase Directory References**:
- Check all references use `tendril/phases/` (not `pairs/phases/`)
- Verify phase directory naming: `phase-XX-name`
- Check all paths in documentation
2. **Verify KB Directory References**:
- Check all references use `kb/` structure
- Verify category directories are correct
- Check special directory references
3. **Verify Documentation Paths**:
- Check all relative paths are correct
- Verify cross-references work
- Check file links are valid
**Files to Check**:
- `.cursorrules` (path references)
- `docs/AGENT-GUIDELINES.md`
- `kb/README.md`
- Phase documentation files
- All guide documents
**Success Criteria**:
- All paths use `tendril/phases/` structure
- All KB paths are correct
- All documentation links work
- No broken references
---
### Task 3: Platform Terminology Verification
**Objective**: Verify all platform references use "Gitea" (not "GitHub")
**Steps**:
1. **Search for GitHub References**:
- Search for "GitHub" (case-insensitive)
- Identify context: platform reference vs. compatibility note
- Document instances found
2. **Verify Platform Terminology**:
- Check all platform references say "Gitea"
- Verify compatibility notes are clear
- Check workflow references use "Gitea Actions"
- Verify repository URL is Gitea instance
3. **Update Any Incorrect References**:
- Replace "GitHub" with "Gitea" where referring to platform
- Keep "GitHub Actions" only in compatibility notes
- Ensure consistency
**Files to Check**:
- `.cursorrules`
- `docs/AGENT-GUIDELINES.md`
- `docs/GITEA/*.md`
- `.github/README.md`
- `.github/LLM-Usage-Guide--tendril.md`
- All phase plans and guides
**Success Criteria**:
- All platform references say "Gitea"
- Compatibility notes are clear
- Repository URL is Gitea instance
- Terminology is consistent
---
### Task 4: Phase Structure Customization
**Objective**: Verify phase numbering and naming are appropriate for Tendril
**Steps**:
1. **Review Phase Numbering**:
- Verify phase numbering starts at 00 (Phase 0: Foundation)
- Check numbering is sequential
- Verify no gaps in numbering
2. **Review Phase Names**:
- Verify phase names are descriptive
- Check naming convention: `phase-XX-name`
- Ensure names reflect actual phase content
3. **Verify Phase Status**:
- Check all phase statuses are accurate
- Verify status indicators: ✅ Complete, 🔄 In Progress, ⏳ Planned
- Update README.md if needed
**Files to Check**:
- `tendril/phases/phase-*/blueprint.md`
- `README.md` (phase status section)
- `PROJECT_STATUS.md` (if exists)
**Success Criteria**:
- Phase numbering is sequential
- Phase names are descriptive and consistent
- Phase statuses are accurate
- README reflects current state
---
### Task 5: KB Category Customization
**Objective**: Verify KB categories are appropriate and routing is correct
**Steps**:
1. **Review KB Categories**:
- Verify all 8 categories exist and are appropriate
- Check category names are clear
- Verify routing decision tree is correct
2. **Verify KB Routing**:
- Check routing decision tree uses correct paths
- Verify Tendril-specific routing (01_projects/tendril/)
- Check routing confidence system is documented
3. **Test KB Routing**:
- Create test KB files for each category
- Verify routing works correctly
- Verify confidence scoring works
**Files to Check**:
- `kb/README.md` (routing decision tree)
- `kb/_guides/KB_INGEST_PROMPT.md` (routing rules)
- KB category directories
**Success Criteria**:
- All KB categories are appropriate
- Routing decision tree is correct
- Routing works for all categories
- Documentation is accurate
---
### Task 6: Final Documentation Review
**Objective**: Comprehensive review of all documentation for accuracy and completeness
**Steps**:
1. **Review Main Documentation**:
- `README.md` - Project overview and status
- `docs/AGENT-GUIDELINES.md` - Agent guidelines
- `.cursorrules` - Cursor rules
- Verify all are up-to-date and accurate
2. **Review Phase Documentation**:
- Check all phase blueprints are complete
- Verify tasks, decisions, changelogs are synchronized
- Check project name consistency
3. **Review KB Documentation**:
- `kb/README.md` - KB system overview
- `kb/_guides/KB_INGEST_PROMPT.md` - Ingestion prompt
- Verify all KB documentation is accurate
4. **Review Workflow Documentation**:
- `.github/README.md` - Workflow overview
- `.github/LLM-Usage-Guide--tendril.md` - LLM guide
- Verify workflow documentation is complete
5. **Review Prompt Documentation**:
- `docs/PROMPTS/LLM-Usage-Guide.md`
- `docs/PROMPTS/Prompt-Creation-Guide.md`
- Verify prompt documentation is complete
**Success Criteria**:
- All documentation is accurate
- All documentation is up-to-date
- All cross-references work
- All examples are relevant to Tendril
---
### Task 7: System Integration Verification
**Objective**: Verify all system components work together correctly
**Steps**:
1. **Test End-to-End Workflows**:
- Test complete KB creation workflow
- Test complete phase documentation update workflow
- Test complete workflow modification workflow
- Verify all components integrate correctly
2. **Verify Automation**:
- Test KB index auto-update
- Test KB lint validation
- Verify automation works as expected
3. **Verify Synchronization**:
- Test phase documentation synchronization
- Test README maintenance
- Verify synchronization rules work
**Success Criteria**:
- All end-to-end workflows function correctly
- Automation works as expected
- Synchronization rules work correctly
- System is ready for ongoing use
---
## Comprehensive Verification Checklist
Before completing Phase 6, verify:
- [ ] No "pairs" references found (except historical)
- [ ] No placeholder names found
- [ ] All project names use "Tendril" or "tendril"
- [ ] All directory paths use `tendril/phases/` structure
- [ ] All platform references say "Gitea" (with compatibility notes)
- [ ] Repository URL is Gitea instance
- [ ] Phase numbering is sequential and appropriate
- [ ] Phase names are descriptive
- [ ] Phase statuses are accurate in README
- [ ] KB categories are appropriate
- [ ] KB routing works correctly
- [ ] All documentation is accurate and up-to-date
- [ ] All cross-references work
- [ ] All examples are relevant to Tendril
- [ ] All end-to-end workflows function correctly
- [ ] Automation works as expected
- [ ] System is ready for ongoing use
---
## Final Customization Checklist
### Project Name
- [ ] All files use "Tendril" or "tendril"
- [ ] No "pairs" references (except historical)
- [ ] No placeholder names
### Directory Structure
- [ ] All paths use `tendril/phases/`
- [ ] All KB paths are correct
- [ ] All documentation links work
### Platform Terminology
- [ ] All platform references say "Gitea"
- [ ] Compatibility notes are clear
- [ ] Repository URL is Gitea instance
### Phase Structure
- [ ] Phase numbering is sequential
- [ ] Phase names are descriptive
- [ ] Phase statuses are accurate
### KB System
- [ ] KB categories are appropriate
- [ ] Routing decision tree is correct
- [ ] Routing works for all categories
### Documentation
- [ ] All documentation is accurate
- [ ] All documentation is up-to-date
- [ ] All cross-references work
---
## Success Criteria
- All customization is complete
- All verification checks pass
- System is fully functional
- Documentation is accurate and complete
- System is ready for ongoing use
- No outstanding issues or inconsistencies
---
## Notes
- Most customization has been done incrementally in previous phases
- This phase focuses on verification and catching anything missed
- Be thorough in searching for placeholder names and incorrect references
- Document any issues found and fix them before marking complete
- System should be production-ready after this phase
---
**Location**: `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-6-PLAN.md`
**Related**:
- All previous phase plans
- `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
- All project documentation