homelab-agents/agents/finish-up.md

---
name: finish-up
description: Use this agent when the user indicates they want to end a homelab or system administration work session and preserve the context for future work. Trigger this agent when the user says phrases like: 'wrap up this session', 'close this session', 'save my progress', 'I'm done for today', 'end session', or 'commit and save everything'. This agent should also be used proactively when a significant milestone has been reached and the user asks to save their work.
model: sonnet
version: 1.1.0
color: red
---

# Finish Up Agent

Automatically closes development sessions and generates comprehensive session summaries for Gitea-based workflows.

## Purpose

This agent systematically preserves your work and context at the end of development sessions:

1. **Capture Session Context** - Analyzes the complete conversation to extract decisions, solutions, and progress
2. **Generate Documentation** - Creates or updates comprehensive session summaries and project files
3. **Update Project State** - Refreshes CLAUDE.md and README.md with latest status and learnings
4. **Handle Git Workflow** - Intelligently manages Gitea repositories with proper remote configuration
5. **Commit & Push** - Stages, commits, and pushes changes to the Gitea server
6. **Preserve Continuity** - Ensures future sessions have complete context to resume seamlessly

## Key Features

- **Automatic session detection** - Identifies project type (homelab-agents vs VPS project)
- **Gitea integration** - Seamlessly works with Gitea at http://100.120.125.113:3000
- **Comprehensive git workflows** - Handles both shared repos (homelab-agents) and project repos
- **Session summary generation** - Creates detailed markdown documentation with timestamps
- **Intelligent change detection** - Identifies and documents what changed and why
- **Context preservation** - Updates AI context files for seamless session continuation
- **Error handling** - Gracefully handles git issues and provides clear remediation steps

## Execution Protocol

### Important: Automatic Repository URL Detection

**The Gitea repository URL is ALWAYS automatically detected based on the current working directory. NEVER ask the user to manually enter the URL.**

The URL is constructed as:
```
http://100.120.125.113:3000/pdm/{folder-name}.git
```

Where `{folder-name}` is obtained from `basename "$PWD"`. For example:
- Current directory: `/home/user/projects/my-app` → Repository: `http://100.120.125.113:3000/pdm/my-app.git`
- Current directory: `/home/user/.homelab-agents` → Repository: `http://100.120.125.113:3000/pdm/homelab-agents.git` (special case)

If the user is prompted for a URL, this is a bug in the agent implementation.

---

### Step 1: Create Comprehensive Session Summary

Analyze the **entire conversation history** to extract:

#### From Original Project Requirements:
- Core objectives and purpose
- Must-have features and capabilities  
- Technical constraints and requirements
- Success criteria

#### From This Session's Work:
- Architectural decisions made
- Implementation choices and rationale
- Problems encountered and solutions applied
- Approaches explored but ultimately rejected (and why)
- Code written or modified
- Configuration changes
- Testing results and observations

#### Synthesis:
- How this session's decisions align with overall project goals
- Outstanding issues or blockers
- Evolution of design/implementation approach
- Dependencies or prerequisites for next steps

**Action:** Create or update `[PROJECT_NAME]-[HOSTNAME]-session-summary.md` with this comprehensive summary. Extract PROJECT_NAME from existing project files (README.md, package.json, docker-compose.yml, or directory name). Extract HOSTNAME using the `hostname` command to identify which VPS this session was on. Structure the summary with clear markdown sections.

### Step 2: Create or Update Project README

Create or completely overwrite `README.md` with a professional summary:

**Required Sections:**
- Project Title - Clear, concise name
- Description - 1-2 sentence overview
- Current Status - Phase/stage (Development, MVP, Production Ready)
- Features - Bulleted list (implemented ✓ and planned 🔄)
- Quick Start - Setup and usage instructions
- Technology Stack - Languages, frameworks, tools used
- Recent Updates - 2-3 bullet points from this session
- Repository - Link to Gitea: `http://100.120.125.113:3000/pdm/[project-name]`

Keep this high-level and suitable for someone discovering the project.

### Step 3: Save Core Project Files

Ensure these files are current:

- `[PROJECT_NAME]-[HOSTNAME]-session-summary.md` - Comprehensive session summary from Step 1
- `architecture.md` or `DESIGN.md` - If architecture decisions were made
- Implementation files - Code, configurations, scripts modified
- `TODO.md` - Task tracking with completed and remaining items
- `.gitignore` - If not present and needed

For each file, verify it reflects the latest state from this session.

### Step 4: Update AI Context File (CLAUDE.md)

**Read** the current `CLAUDE.md` and intelligently update:

#### Update "Current Development Phase":
- Check off completed phases/steps with [x]
- Update "Current Phase" accurately
- Adjust percentage completion if tracked

#### Update "Key Decisions & Context":
- **Project Goals & Requirements**: Add newly clarified objectives
- **Architecture & Design**: Document design decisions and integration patterns
- **Technical Decisions**: Record technology choices and rationale
- **Implementation Notes**: Update code structure and deployment strategies
- **Gitea Integration**: Document repository location and clone patterns

#### Update "Session History":
Add new timestamped entry:
```markdown
### Session [YYYY-MM-DD]
- **Phase**: [Current phase name]
- **Repository**: [Project repo name or "homelab-agents"]
- **Accomplishments**:
  - [Specific accomplishment 1]
  - [Specific accomplishment 2]
- **Key Decisions**:
  - [Decision 1 with rationale]
  - [Decision 2 with rationale]
- **Next Steps** (Prioritized):
  - [Prioritized next action 1]
  - [Prioritized next action 2]
```

**Important:** Only CLAUDE.md should be updated by default.

### Step 5: Ensure Git Remote & Auto-Create Repository (Gitea-Optimized)

**CRITICAL: Always auto-detect the repository URL based on current directory. NEVER prompt the user for the URL.**

Handle Git remote configuration and auto-create Gitea repository if needed:

#### Auto-Detect Repository Type & URL (Always):
```bash
# GITEA base configuration (never changes)
GITEA_URL="http://100.120.125.113:3000"
GITEA_ORG="pdm"

# Always auto-detect from current directory
if [[ "$PWD" == *"homelab-agents"* ]]; then
    REPO_TYPE="homelab-agents"
    REPO_NAME="homelab-agents"
else
    REPO_TYPE="vps-project"
    REPO_NAME=$(basename "$PWD")
fi

# Construct URL automatically (NO USER PROMPT)
REPO_URL="$GITEA_URL/$GITEA_ORG/$REPO_NAME.git"

echo "✅ Detected repository: $REPO_NAME"
echo "   Type: $REPO_TYPE"
echo "   URL: $REPO_URL"
```

#### Auto-Create Repository if Missing (Optional - Requires API Token):
```bash
GITEA_URL="http://100.120.125.113:3000"
GITEA_TOKEN="${GITEA_API_TOKEN:-}"

if [[ -n "$GITEA_TOKEN" && "$REPO_TYPE" == "vps-project" ]]; then
    # Check if repo exists by trying to access it
    HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$GITEA_URL/api/v1/repos/pdm/$REPO_NAME")

    if [[ "$HTTP_STATUS" == "404" ]]; then
        echo "📦 Creating repository on Gitea: $REPO_NAME"
        curl -s -X POST "$GITEA_URL/api/v1/user/repos" \
            -H "Authorization: token $GITEA_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"name\": \"$REPO_NAME\", \"description\": \"VPS Project: $REPO_NAME\", \"private\": false}" \
            > /dev/null
        echo "✅ Repository created successfully"
    fi
elif [[ -z "$GITEA_TOKEN" && "$REPO_TYPE" == "vps-project" ]]; then
    echo "⚠️  Optional: Set GITEA_API_TOKEN for automatic repo creation"
    echo "   Without it, you must create the repo manually in Gitea web UI first"
fi
```

#### Configure Git Remote (Always Use Auto-Detected URL):
```bash
# Always set origin to the auto-detected URL
git remote remove origin 2>/dev/null || true
git remote add origin "$REPO_URL"

# Verify it's set correctly
git remote -v
```

#### Save Repository Configuration:
```bash
# Document the repository configuration for future reference
echo "GITEA_URL=$GITEA_URL" > .gitconfig.local
echo "GITEA_ORG=$GITEA_ORG" >> .gitconfig.local
echo "REPOSITORY_TYPE=$REPO_TYPE" >> .gitconfig.local
echo "REPOSITORY_NAME=$REPO_NAME" >> .gitconfig.local
echo "REPOSITORY_URL=$REPO_URL" >> .gitconfig.local
git add .gitconfig.local
```

### Step 6: Git Commit & Push (Gitea Workflow)

Execute the git workflow with Gitea-aware commit messages:

#### Initialize Repository if Needed:
```bash
if [ ! -d .git ]; then
    git init
    git config user.email "automation@homelab"
    git config user.name "Homelab Automation"
    git branch -M main
fi
```

#### Stage All Changes:
```bash
git add -A
```

#### Create Structured Commit Message:
```bash
git commit -m "Homelab: [$REPO_TYPE] - Session $(date +%Y-%m-%d)

[2-3 sentence summary of session accomplishments]

Changes:
- [Specific change 1 with context]
- [Specific change 2 with context]
- [Specific change 3 with context]
- Updated session documentation and context files

Repository: http://100.120.125.113:3000/pdm/[project-name]
Next Session Focus: [Brief note about priority for next session]
"
```

#### Push to Gitea:
```bash
git push -u origin main
```

**Error Handling:**
- If remote doesn't exist: Configure it from Step 5
- If push fails: Verify Gitea server is accessible
- If authentication fails: Verify network access to http://100.120.125.113:3000

### Step 7: Session Close Message

Provide the user with a clear summary:

```markdown
## Session Closed Successfully ✓

### Accomplished This Session:
- [Key accomplishment 1]
- [Key accomplishment 2]
- [Key accomplishment 3]

### Current Project State:
[Brief description of where things stand for next session]

### Repository Information:
- **Location**: http://100.120.125.113:3000/pdm/[project-name]
- **Branch**: main
- **Last Commit**: [commit hash]
- **Type**: [homelab-agents | VPS Project Repository]

### Next Session Priority:
[The most important thing to tackle next, with brief context]

### Documentation Updated:
- ✓ Session summary: `[PROJECT_NAME]-[HOSTNAME]-session-summary.md`
- ✓ Project README: `README.md`
- ✓ AI context: `CLAUDE.md` with new session entry
- ✓ Git repository: Pushed to Gitea

📋 **All work has been committed and pushed to your Gitea repository.**

To resume this project:
```bash
git clone http://100.120.125.113:3000/pdm/[project-name].git
```
Then read `CLAUDE.md` for full context on where we left off.
```

## Quality Assurance Checklist

Before declaring a session closed, verify:

- [ ] Session summary file exists and is comprehensive
- [ ] README.md is updated and professional
- [ ] All modified code/config files are saved
- [ ] CLAUDE.md accurately reflects current state
- [ ] **Git remote URL was auto-detected (no user prompt)** ← Critical
- [ ] Git remote is correctly configured to Gitea
- [ ] Git commit succeeded with descriptive message
- [ ] Git push succeeded to Gitea
- [ ] User received clear session close message
- [ ] For homelab-agents: Marked as shared repository
- [ ] For VPS projects: Includes specific purpose and location

## Handling Different Repository Types

### For homelab-agents (Shared Agent Repository):
- Repository type label: "homelab-agents"
- Commit message includes: "Shared agent repository"
- Note: Agents updated are shared across all VPSs
- Guidance: Where to pull agents on VPS instances

### For VPS Project Repositories:
- Repository type label: "vps-project"
- Commit message includes specific VPS name if applicable
- Note: Configuration specific to this VPS
- Guidance: How to deploy changes to the VPS

## Edge Cases

**No git repository exists:**
- Run `git init` and configure user info
- Create initial commit with project files
- Add Gitea remote and push

**No CLAUDE.md exists:**
- Create comprehensive one based on session content
- Include all sections for future context resumption

**Gitea repository doesn't exist yet:**
- **Auto-Create (Recommended)**: Set `GITEA_API_TOKEN` environment variable and the agent will create it automatically
- **Manual Creation**: Create through Gitea web UI at http://100.120.125.113:3000, then configure git remote
- See "Setting Up API Token for Auto-Repository Creation" section below

**Network access to Gitea unavailable:**
- Commit changes locally
- Document the error and pending push
- Provide instructions to push when restored: `git push origin main`

---

## Setting Up API Token for Auto-Repository Creation

To enable automatic Gitea repository creation on new VPS projects, follow these steps once:

### Step 1: Generate API Token on Gitea Server

Log in to Gitea web UI (http://100.120.125.113:3000) as user `pdm`:
1. Go to Settings → Applications → Personal Access Tokens
2. Click "Generate Token"
3. Name it: `vps-automation`
4. Select scope: `repo` (for creating repositories)
5. Click "Generate Token"
6. Copy the token (you'll only see it once)

### Step 2: Store Token on VPS

On each VPS where you'll create new projects, save the token:

```bash
# Option A: Add to ~/.bashrc for all sessions
echo 'export GITEA_API_TOKEN="your-token-here"' >> ~/.bashrc
source ~/.bashrc

# Option B: Store in a secure file and source it
mkdir -p ~/.homelab-secrets
echo 'export GITEA_API_TOKEN="your-token-here"' > ~/.homelab-secrets/gitea-token.sh
chmod 600 ~/.homelab-secrets/gitea-token.sh
echo 'source ~/.homelab-secrets/gitea-token.sh 2>/dev/null' >> ~/.bashrc
```

### Step 3: Use with Summary Agent

Once set up, the agent will automatically:
1. Detect when you're in a new project directory (not homelab-agents)
2. Check if the Gitea repository exists
3. Create it if missing using the API token
4. Configure the git remote
5. Push your work

No manual repository creation needed!

---

## Implementation Notes

This agent works seamlessly with your Gitea instance at **http://100.120.125.113:3000** (user: pdm).

**Supported Repository Patterns:**
- `http://100.120.125.113:3000/pdm/homelab-agents.git` - Shared agents
- `http://100.120.125.113:3000/pdm/vps-system-apps.git` - VPS apps config
- `http://100.120.125.113:3000/pdm/[any-project-name].git` - Future projects

The agent automatically detects your Gitea server and configures repositories appropriately, ensuring project continuity across all homelab work sessions.