tendril/kb/_guides/PROJECT-SETUP-GUIDE/PHASE-3-PLAN.md

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