| title | Team Repository Kit | |||||
|---|---|---|---|---|---|---|
| description | Starter kit for hackathon team repositories with narrative context, personas, stage guides, cheat sheets, and visual assets | |||||
| author | Paula Silva, AI-Native Software Engineer, Americas Global Black Belt at Microsoft | |||||
| date | 2026-04-24 | |||||
| version | 1.3.0 | |||||
| status | approved | |||||
| tags |
|
📍 Start here if you are a hackathon participant.
- First: follow
SETUP.mdto create your team's GitHub repo, configure Copilot, and install Spec-Kit + Specky (30 minutes).- Then: read
TEAM-FLOW.mdto understand how the 10 of you work together.- Finally: open your persona kit in
persona-kits/<your-role>/README.md, then go to Stage 1 at01-arqueologia/GUIDE.md.
Setup Guide · Team Flow · The SIFAP Story · Your Mission · Your Team · Stage Flow
- The SIFAP Story
- Why SIFAP Must Change
- Your Mission in 8 Hours
- Your Team
- The Four Stage Journey
- The 4 SDLC Agents
- From Legacy to Modern
- Folder Structure
- How to Use This Kit
- Related Repositories
- References
Picture this. It is 1995. A small team of engineers at DATACORP builds a system to pay social benefits to millions of citizens. They pick the best tools available at the time: Natural, a language designed for fast data processing, and Adabas, a hierarchical database known for reliability. They name it SIFAP, the Sistema Integrado de Folha de Pagamentos.
The system works. It pays citizens on time, month after month. The people who built it move on. New people are hired. The business changes. Laws change. Payments rules change. Every few years, someone patches SIFAP to handle a new rule, a new benefit category, a new exception. Nobody rewrites it. Nobody dares to. It just keeps running.
Fast forward to 2026. SIFAP is still running. It processes millions of payments every month. But it is not the quiet hero it used to be. It has become a burden.
- The original architects are long gone.
- The source code has abbreviations nobody remembers the meaning of.
- Every change requires a week of testing, because there are no automated tests.
- The mainframe licenses cost the company more every year.
- Citizens want to check their benefits from a phone. SIFAP has no API.
- Partners want to integrate. SIFAP has no modern endpoint.
- Operators still use green screen terminals. Nobody under 35 knows how to navigate them.
That is where your team comes in. You have 1 day, 100 developers, 10 teams, and a box full of AI tools. Your mission is to prove that legacy modernization, the kind that used to take 2 years and a consulting army, can now happen in hours, with the right approach.
Welcome to the Hackathon DATACORP 2026.
| # | Pain Point | Business Impact |
|---|---|---|
| 1️⃣ | Knowledge silos | A handful of people know how SIFAP works. When they leave, the company is exposed. |
| 2️⃣ | Cryptic code | 8 character abbreviations, no comments, no docs. Every change starts with archaeology. |
| 3️⃣ | Zero tests | Changes are gambles. A fix in one module silently breaks another from 15 years ago. |
| 4️⃣ | Costly licenses | Mainframe licenses consume budget that should fund innovation. |
| 5️⃣ | No integrations | Mobile, partners, modern channels. All blocked by the monolith. |
💡 Analogy. Legacy SIFAP is like a 30 year old family car that still runs but needs a full tank of gas, a carburetor adjustment every month, and only one mechanic in town can service it. Modernizing is not about buying a faster car. It is about trading it for a reliable electric vehicle the whole family can drive.
Your team has one clear goal. Rebuild SIFAP with a modern stack, prove that AI assisted Spec Driven Development delivers, and ship something demo worthy by the end of the day.
| Deliverable | Format | Stage |
|---|---|---|
| 🗺️ Legacy map and glossary | Markdown in 01-arqueologia/ |
Stage 1 |
| 📜 Modern specification | EARS requirements + ADRs in the reference modern spec (provided by facilitators) | Stage 2 |
| 💻 Working prototype | Java 21 + Next.js 15 code | Stage 3 |
| ☁️ Infrastructure and CI/CD | Terraform + GitHub Actions | Stage 4 |
| 🎤 Final pitch | 5 minute demo | End of day |
Each team has 10 people. The facilitators provide 25 persona kits. You can pick any combination that fits your team and the work you need to do.
| Persona | Role | Primary Tool | Delivers |
|---|---|---|---|
| 🧠 Tech Lead | Architecture and decisions | Specky SDD + Copilot Chat | ADRs, reviews, alignment |
| ☕ Backend Developer | Services and APIs | Java 21 + Spring Boot | REST API, domain, services |
| ⚛️ Frontend Developer | Web experience | Next.js 15 + TypeScript | UI, pages, API integration |
| 🛠️ DevOps Engineer | Infra and pipelines | Terraform + GitHub Actions | IaC modules, CI/CD |
| 🧪 QA Engineer | Quality and coverage | Vitest + pytest | Test suite, quality gates |
🎒 Need more specialized roles? The
persona-kits/folder has 25 kits including Product Owner, UX Designer, DBA, SRE, AppSec Engineer, Compliance Auditor, and more. Pick what your team needs.
flowchart LR
S1["🔍 Stage 1<br/>Archaeology<br/>3h"]
S2["📜 Stage 2<br/>Modern Spec<br/>2h"]
S3["💻 Stage 3<br/>Implementation<br/>2h"]
S4["🚀 Stage 4<br/>Evolution<br/>1h"]
S1 --> S2 --> S3 --> S4
S4 --> D["🎤 Demo<br/>and Pitch"]
classDef stage fill:#0f172a,stroke:#334155,color:#e2e8f0
class S1,S2,S3,S4,D stage
| Stage | Folder | What your team does |
|---|---|---|
| 🔍 Archaeology | 01-arqueologia/ |
Explore SIFAP, map rules, find the hidden mysteries |
| 📜 Modern Spec | 02-spec-moderna/ |
Write EARS requirements, capture ADRs, design the target |
| 💻 Implementation | 03-implementacao/ |
Build Java backend, Next.js frontend, PostgreSQL schema |
| 🚀 Evolution | 04-evolucao/ |
Terraform to Azure, GitHub Actions pipeline, final demo |
If the persona-kits are the vertical axis — one kit per role — the 4 stage agents are the horizontal axis — one agent per stage of the day. Every persona uses every agent, but the spotlight shifts as the clock advances. Agents know how to modernize Natural/Adabas systems; they do not know anything specific about your legacy system. That knowledge emerges from your investigation.
| Agent | Stage | Mission | Kit |
|---|---|---|---|
@archaeologist-agent |
1 — Archaeology | Read legacy code, extract rules, map dependencies, catalog mysteries | agent-kits/01-archaeologist/ |
@architect-agent |
2 — Modern Spec | Carve bounded contexts, write EARS, generate ADRs, design Modular Monolith | agent-kits/02-architect/ |
@builder-agent |
3 — Implementation | Translate legacy to Java 21, generate JPA, write tests, build REST + Next.js | agent-kits/03-builder/ |
@evolution-agent |
4 — Evolution | Write GitHub Issues for Copilot Agent, review AI PRs, set up CI/CD and IaC | agent-kits/04-evolution/ |
See docs/persona-agent-matrix.md for the full 10×4 mapping of who uses what.
See docs/4-agents-explained.md for the anatomy of each agent.
See docs/sdlc-flow-guide.md for the complete integration map — who does what, with which agent, at which stage, with every handoff and deliverable in sequence.
💡 Think of it as a kitchen renovation. The legacy SIFAP is a kitchen from 1995: functional, but tight, hard to clean, with appliances only one brand still services. The modern SIFAP is an open, modular kitchen where every appliance speaks a standard protocol, and anyone can plug in new devices.
| 📁 Path | 🎯 Purpose |
|---|---|
SETUP.md |
🚀 Read first. Step-by-step: create repo, configure Copilot, install Spec-Kit + Specky |
TEAM-FLOW.md |
🤝 Daily timeline, handoffs, the 20-minute rule |
personas/ |
👤 The 10 persona cards — read your role |
01-arqueologia/ |
🔍 Stage 1: legacy code archaeology guides and Copilot prompts |
02-spec-moderna/ |
📜 Stage 2: EARS specification templates and ADR scaffolds |
03-implementacao/ |
💻 Stage 3: implementation scaffolding and Copilot Agent prompts |
04-evolucao/ |
🚀 Stage 4: Terraform guides and CI/CD templates |
cheat-sheets/ |
⚡ Quick reference cards: Copilot modes, Specky workflow, model routing |
persona-kits/ |
🤖 25 Copilot agent kits, each with agents, prompts, skills, and a README |
agent-kits/ |
🤖 4 SDLC stage agents (archaeologist, architect, builder, evolution) |
plugins/ |
🔌 Shared Copilot plugins (GitHub Issues, Azure Boards sync) |
scripts/ |
🛠️ setup.sh (bootstrap) and check.sh (run all CI gates locally) |
docs/ |
📚 Team-curated docs: ADRs, glossary, runbook, agent guides |
assets/ |
🖼️ SVG illustrations used across this kit |
.github/ |
⚙️ Issue templates, PR template, Copilot instructions, workflows |
.devcontainer/ |
📦 Pre-configured dev environment (Java 21, Node 20, Docker) |
The stage guides mention these external folders. Facilitators distribute them at the start of the event, or you run ./scripts/setup.sh to clone them as symlinks. Either way, the paths in the guides will work.
| Stage | Folder | Purpose |
|---|---|---|
| 1 | legacy/ |
Natural programs, Adabas DDMs, legacy docs (sifap-legacy) |
| 2 | — | Reference modern specification (read on GitHub: reference modern spec (shared by facilitators)) |
| 3 | prototype/ |
Reference prototype (Java + Next.js) |
| 4 | infra/ |
Reference Terraform modules for Azure |
Full step-by-step setup is in SETUP.md — covers GitHub repo creation, Copilot activation, Spec-Kit + Specky installation, branch strategy, and the 13-item smoke test.
Quick summary (full instructions in SETUP.md):
# 1. Create your team's GitHub repo — empty, under YOUR account (one person, once)
gh repo create hackathon-team-XX --private
# 2. Bootstrap from this kit
git clone https://github.com/paulasilvatech/hackathon-datacorp-team-kit.git kit
cp -R kit hackathon-team-XX
cd hackathon-team-XX
rm -rf .git
git init -b main
git remote add origin https://github.com/<YOUR_GITHUB_USER>/hackathon-team-XX.git
# 3. Bootstrap script (clones sifap-legacy, sets up symlinks)
./scripts/setup.sh
# 4. First commit and push
git add -A && git commit -m "chore: bootstrap team kit" && git push -u origin main
# 5. Open in VS Code with the dev container
code .
# Then: Ctrl+Shift+P > "Dev Containers: Reopen in Container"
⚠️ Heads up. The reference prototype and Terraform modules are delivered by facilitators at the start of Stages 3 and 4 respectively. Do not attempt to fetch them from this repository.
- 🚀
SETUP.md— get your environment ready (30 min) - 🤝
TEAM-FLOW.md— understand how the 10 of you collaborate - 📖 Your persona card in
personas/<your-role>.md - 🤖 Your Copilot agent kit in
persona-kits/<your-role>/README.md - ⚡ Cheat sheets in
cheat-sheets/(keep them open in a tab) - 🔍 Stage 1 guide in
01-arqueologia/GUIDE.md
| Repository | Purpose |
|---|---|
| hackathon-datacorp-team-kit | 🎒 This repository — team starter kit |
| sifap-legacy | 🗄️ Read-only legacy SIFAP code (Natural + Adabas) for Stage 1 |
Reference materials live in the main event repository and are shared by facilitators.
| 📖 Resource | 🎯 What you get |
|---|---|
| Hackathon Blueprint | Event plan, schedule, rubric |
| SIFAP Modern Specification | Complete EARS spec for the target system |
| Reference Prototype | Working Java + Next.js implementation |
| Facilitator Playbook | Session scripts, coaching cues, fallback plans |
| Previous | Home | Next |
|---|---|---|
| Team Flow | This kit | Stage 1: Archaeology |
Authored by Paula Silva, AI-Native Software Engineer, Americas Global Black Belt at Microsoft. Version 1.3.0, April 2026.