commit 088ac3bc66cb1356a07119b135030e89882820f3
Author: timmy <timmy@stackchain.ai>
Date:   Mon Jul 6 23:44:13 2026 +0000

    docs: add hackathon README with parameters and 5 project ideas

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..730cbf8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,90 @@
+# 🚀 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. 🚀