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:

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

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:

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)