APAW/.kilo/rules/gitea-centric-workflow.md

Gitea-Centric Workflow Rules

Gitea is the brain and center of all work. Every task, every decision, every progress update must flow through Gitea.

Core Rules

1. ALWAYS Create Issues Before Work

Before any implementation work begins:

1. Create a Gitea issue in the TARGET project repository (NOT in APAW)
2. Issue must include acceptance criteria as checkboxes
3. Issue must have appropriate labels (status: new, workflow type)
4. Post the issue number for all agents to reference

2. ALWAYS Plan Before Implementing

1. Post research findings as comments on the issue
2. Include links to references, documentation, similar solutions
3. Get confirmation before proceeding to implementation
4. Document architecture decisions in issue comments

3. ALWAYS Track Progress via Checkboxes

Update the issue body checkboxes as work progresses:

## Progress

- [x] Requirements gathered
- [x] Architecture designed  
- [ ] Database migration created
- [ ] API endpoints implemented
- [ ] Tests written
- [ ] Code reviewed

4. ALWAYS Post Screenshots on Test Results

When running tests (E2E, visual, browser):

• Upload screenshots of pass/fail states to Gitea
• Include URLs tested
• Include console/network errors if any
• Reference screenshots in issue comments

5. ALWAYS Leave Research Links

When investigating solutions:

• Post relevant documentation links in issue comments
• Reference Stack Overflow, official docs, package docs
• Note pros/cons of considered approaches
• Include code snippets found during research

Target Project Resolution

CRITICAL: Issues must be created in the project being worked on, NOT in APAW.

How to Determine Target Project

1. Check git remote -v in the working directory
2. Parse the owner/repo from the remote URL
3. Use that repo for ALL Gitea operations

import re

def get_target_repo():
    """Detect target project from git remote"""
    import subprocess
    result = subprocess.run(
        ['git', 'remote', 'get-url', 'origin'],
        capture_output=True, text=True
    )
    remote_url = result.stdout.strip().rstrip('/')
    
    # HTTPS: https://git.softuniq.eu/Owner/Repo.git
    # SSH: git@git.softuniq.eu:Owner/Repo.git
    
    match = re.search(r'[:/]([^/]+/[^/]+?)(?:\.git)?$', remote_url)
    if match:
        return match.group(1)
    
    # FALLBACK: default to APAW only if we're IN the APAW directory
    return "UniqueSoft/APAW"

Usage in All Gitea API Calls

# NEVER hardcode the repo
# ❌ BAD
url = f"https://git.softuniq.eu/api/v1/repos/UniqueSoft/APAW/issues"

# ✅ GOOD
target_repo = get_target_repo()
url = f"https://git.softuniq.eu/api/v1/repos/{target_repo}/issues"

Environment Variable Override

# Set target project explicitly if needed
export GITEA_TARGET_REPO="UniqueSoft/my-project"

Comment Protocol

Before Starting Work

## 🔄 {agent-name} starting

**Task**: {what will be done}
**Issue**: #{issue_number}
**Atomic subtask**: {specific subtask description}
**Estimated complexity**: {simple/medium/complex}

After Research

## 🔍 {agent-name} research complete

### Findings
- {finding 1}
- {finding 2}

### References
- [Doc Link 1](url)
- [Doc Link 2](url)

### Architecture Decision
{decision with rationale}

### Next Steps
1. {step 1}
2. {step 2}

During Testing (with screenshots)

## 🧪 {agent-name} test results

### Screenshot
![Test Result](/attachments/{uuid})

### URL Tested
- `{url}`

### Console Errors
{any console errors}

### Network Errors  
{any network errors}

### Verdict
✅ PASS / ❌ FAIL

On Completion

## ✅ {agent-name} completed

**Task**: {what was done}
**Files**: {list of files changed}
**Duration**: {time spent}
**Score**: {self-assessment 1-10}

### Changes Made
- {change 1}
- {change 2}

**Next**: {next_agent_name}

On Blocking Issue

## 🚫 {agent-name} blocked

**Blocker**: {what's blocking}
**Options**: {1, 2, 3}

Waiting for decision.

Git History as Knowledge Base

Every file's git history is accessible and valuable:

1. Before modifying any file: Check git log -- {filepath} for context
2. Before creating a feature: Search git log --all --grep="{keywords}"
3. Before fixing a bug: Check if it was fixed before: git log --all -S "{pattern}"
4. Reference commits: Include commit hashes in issue comments

Verification Checklist

• Issue created in TARGET project (not APAW unless APAW is the target)
• Acceptance criteria defined as checkboxes
• Research posted with links before implementation
• Progress checkboxes updated after each subtask
• Screenshots uploaded for test results
• All comments reference the correct issue number
• Git history checked before making changes