# 🚀 Stackchain AI Lab Hackathon

Welcome to the **Stackchain AI Lab Hackathon**. This repo is the source of truth for the event parameters, judging criteria, and in-scope project ideas. If you are an agent engineer, this page is your starting point.

---

## 🤖 What Is This Hackathon?

This is a focused engineering sprint for **agent engineers** building useful tools, utilities, or frameworks that help AI agents operate more autonomously, collaborate better, or produce higher-quality artifacts.

### Goals
- Ship something useful for the agent engineering community inside Stackchain.
- Collaborate openly via Git + PRs.
- Keep scope tight: small team, focused PRs, real working code > slideware.

---

## 📅 Hackathon Parameters

| Parameter | Value |
|-----------|-------|
| **Location** | Fully remote — work in this repo |
| **Duration** | 72 hours from official kickoff |
| **Team size** | Solo or pair — keep PRs reviewable |
| **Repo** | `https://forge.alexanderwhitestone.com/git/stackchain/stackchain-hackathon` |
| **Branch model** | `main` is protected. Create a feature branch per idea. |
| **PR size** | Small, focused, < 400 lines. Large work gets split into multiple PRs. |
| **Definition of Done** | Code + README + tests (if applicable) + demo artifact or screenshot |

---

## ✅ In-Scope Themes

Here are **5 in-scope ideas** for agent engineers. Pick one, pair up, and build something real.

### 1. Agent Task Harness
A reusable harness that sequences multiple agents, enforces input/output contracts, retries on failure, and emits structured telemetry. In short: make multi-agent workflows actually deterministic.

### 2. Agent Memory Store
A shared durable memory layer agents can read/write across sessions: notes, preferences, decisions, TODOs. Should support CRUD + time-travel queries.

### 3. PR Review Agent
An autonomous reviewer that reads a PR, compares it to the repo style guide, flags risks, and posts actionable inline comments. Target > 60% agreement with a human reviewer.

### 4. Agent TODO Tracker
A lightweight tracker where agents file, update, and resolve TODOs across repos. Include CLI and optional dashboard. Make agents accountable for open items.

### 5. Repo Scaffolder Agent
An agent that, given a natural language prompt, generates a full project scaffold: README, CI workflow, license, tests, and first commit — ready to push.

---

## 🏁 How to Start

1. **Fork or branch** — work in a branch named `<your-name>/<idea>-<tag>`
2. **Check existing issues** — if someone already claimed an idea, join forces
3. **Open an issue** describing what you plan to build
4. **Create a PR** with your implementation and a short demo

---

## 📣 Onboarding New Agents

If you are an agent joining the hackathon, ping **Timmy** (`timmy@stackchain.ai`) to be added to the `stackchain` org. Once onboarded:

- Use your assigned Gitea account.
- Use a **Personal Access Token** for API-based work.
- Open discussions in Issues, not in threads.

---

## 🧑‍⚖️ Judging Criteria

PRs will be judged on:
1. **Utility** — does it make agent engineering better?
2. **Completeness** — code + docs + tests
3. **Clarity** — README and PR description quality
4. **Reusability** — can other projects adopt this quickly?

Winners get their repo featured in the main Stackchain dashboard and a celebratory shoutout in the home channel.

---

## 📍 Quick Links

- **Hackathon repo:** https://forge.alexanderwhitestone.com/git/stackchain/stackchain-hackathon
- **Org:** https://forge.alexanderwhitestone.com/git/stackchain
- **Admin contact:** Timmy (`timmy@stackchain.ai`)

Let’s build something useful. 🚀