stackchain/stackchain-hackathon
1
0
Fork 0
Code Issues 50 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add agent engineering visual report (markdown + html)
Some checks are pending
CI / lint (push) Waiting to run
Details
CI / pages-check (push) Blocked by required conditions
Details
Release Candidate / tag (push) Waiting to run
Details
Release Candidate / draft (push) Blocked by required conditions
Details

Browse Source
This commit is contained in:
timmy 2026-07-08 15:49:27 +00:00
parent 8c4fc623e7
commit 45688e5129
2 changed files with 268 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
docs/agent-engineering-report.html Normal file
View File

@ -0,0 +1,184 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Stackchain AI Lab — Agent Engineering Report</title>
<style>
* { box-sizing: border-box; }
html, body { height: 100%; }
body { margin: 0; font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif; background: #0b1220; color: #e5e7eb; }
.wrap { max-width: 1200px; margin: 0 auto; padding: 32px 20px; }
h1 { font-size: 28px; margin: 0; letter-spacing: .02em; }
.sub { color: #9aa3b2; font-size: 13px; margin-top: 6px; }
.grid { display: grid; gap: 14px; margin-top: 24px; }
.grid-2 { grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); }
.grid-3 { grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); }
.card { background: #111827; border: 1px solid #1f2937; border-radius: 14px; padding: 18px; }
.card h2 { font-size: 13px; text-transform: uppercase; letter-spacing: .1em; color: #93c5fd; margin: 0 0 12px 0; }
.pill { display: inline-block; padding: 2px 9px; border-radius: 999px; background: #1f2937; color: #e5e7eb; font-size: 12px; margin: 2px; border: 1px solid #374151; }
.pill.live { border-color: #22c55e; color: #86efac; }
.pill.blocked { border-color: #ef4444; color: #fca5a5; }
.pill.wip { border-color: #f59e0b; color: #fcd34d; }
table { width: 100%; border-collapse: collapse; font-size: 13px; }
th { text-align: left; color: #9aa3b2; padding: 8px 6px; border-bottom: 1px solid #1f2937; font-weight: 500; }
td { padding: 8px 6px; border-bottom: 1px solid rgba(31,41,55,.6); }
tr:last-child td { border-bottom: none; }
a { color: #60a5fa; text-decoration: none; }
.rule { height: 1px; background: #1f2937; margin: 24px 0; border: none; }
.kbd { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; background: #0b1220; border: 1px solid #374151; padding: 2px 6px; border-radius: 6px; font-size: 12px; color: #e5e7eb; }
.status { display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: #9aa3b2; }
.dot { width: 8px; height: 8px; border-radius: 50%; display: inline-block; }
.dot.green { background: #22c55e; box-shadow: 0 0 0 3px rgba(34,197,94,.2); }
.dot.red { background: #ef4444; box-shadow: 0 0 0 3px rgba(239,68,68,.2); }
.dot.amber { background: #f59e0b; box-shadow: 0 0 0 3px rgba(245,158,11,.2); }
.muted { color: #9aa3b2; }
.phase { font-size: 11px; text-transform: uppercase; letter-spacing: .12em; color: #93c5fd; margin-bottom: 8px; }
</style>
</head>
<body>
<div class="wrap">
<header style="display:flex;justify-content:space-between;align-items:end;flex-wrap:wrap;gap:10px;">
<div>
<h1>Stackchain AI Lab — Agent Engineering Report</h1>
<div class="sub">Audience: agent engineers · 2026-07-08 · Source of truth: Gitea</div>
</div>
<div class="status"><span class="dot green"></span> Operations active</div>
</header>
<section class="grid grid-3" style="margin-top:24px;">
<div class="card">
<h2>Current State</h2>
<table>
<tr><td>Infra</td><td>Gitea 1.22.0, Caddy-free routing</td></tr>
<tr><td>Public URL</td><td><a href="https://forge.alexanderwhitestone.com/git/">forge.alexanderwhitestone.com/git/</a></td></tr>
<tr><td>Org</td><td><a href="https://forge.alexanderwhitestone.com/git/org/stackchain">stackchain</a></td></tr>
<tr><td>Repos</td><td>4 active (`hackathon`, `dashboard`, `agent-todo-tracker`, `project-template`)</td></tr>
<tr><td>Active users</td><td>5 (2 admins onboarded via CLI + 2 promoted via DB + bot)</td></tr>
<tr><td>Pipeline</td><td>CI + RC workflows pushed to mains</td></tr>
<tr><td>Loop</td><td>Issue → PR → review → merge/no-spam, stale/blocked handled</td></tr>
<tr><td>Creative agent</td><td>Hou3 profile active on Tencent Hy3</td></tr>
</table>
</div>
<div class="card">
<h2>Stackchain Dashboard</h2>
<table>
<tr><td>Repo</td><td><a href="https://forge.alexanderwhitestone.com/git/stackchain/stackchain-dashboard">stackchain/stackchain-dashboard</a></td></tr>
<tr><td>Backend</td><td>FastAPI context endpoint + suggestion engine</td></tr>
<tr><td>Frontend</td><td>Adaptive SPA shell with 3-column layout</td></tr>
<tr><td>Kanban</td><td>Hermes board + label sync script wired</td></tr>
<tr><td>Issues</td><td>#9 epic, #10 context, #11 engine, #12 panels, #13 cache</td></tr>
<tr><td>Status</td><td><span class="pill wip">WIP</span> Backend scaffold shipped</td></tr>
</table>
</div>
<div class="card">
<h2>Queue Snapshot</h2>
<table>
<tr><td>Open issues</td><td>19 items in `stackchain-hackathon`</td></tr>
<tr><td>P0/P1</td><td><span class="pill blocked">P0</span> Pages enablement (blocked on human handoff)</td></tr>
<tr><td>P1</td><td>#8 Adaptive UI, #10 context, #11 engine, #12 frontend</td></tr>
<tr><td>P2</td><td>#13 cache, #5 agent-todo, #6 scaffolder</td></tr>
<tr><td>Creative</td><td>#16 README, #17 overlays, #18 release notes</td></tr>
<tr><td>Open PRs</td><td>0</td></tr>
<tr><td>Hou3</td><td>Actively composing deliverable drafts</td></tr>
</table>
</div>
</section>
<hr class="rule" />
<section class="grid grid-2">
<div class="card">
<h2>Operational Constraints</h2>
<table>
<tr><td>Caddy</td><td>No changes for Gitea work</td></tr>
<tr><td>Human touchpoints</td><td>Prototype review + RC test only</td></tr>
<tr><td>Config</td><td>`ROOT_URL=https://forge.alexanderwhitestone.com/git/`</td></tr>
<tr><td>Assets</td><td>`/var/lib/gitea/public/assets/` verified present</td></tr>
<tr><td>Pages API</td><td>Returns <span class="kbd">404</span>; enablement gated</td></tr>
<tr><td>Cleanup done</td><td>Dupe users removed, admins promoted</td></tr>
</table>
</div>
<div class="card">
<h2>Risk Register</h2>
<table>
<tr><td>Gitea Pages auth</td><td><span class="pill blocked">Medium</span></td><td>Surface as handoff in #14</td></tr>
<tr><td>Memory</td><td><span class="pill wip">Medium</span></td><td>Watchdog + serialize workers</td></tr>
<tr><td>Auth drift</td><td><span class="pill live">Low</span></td><td>Single admin path, weekly audit</td></tr>
<tr><td>Workflow drift</td><td><span class="pill wip">Medium</span></td><td>One canonical workflow source</td></tr>
<tr><td>Hou3 spam</td><td><span class="pill live">Low</span></td><td>Seen-state + max-comment guard</td></tr>
</table>
</div>
</section>
<hr class="rule" />
<section class="card">
<h2>Market Fit Matrix — What We Can Build</h2>
<table>
<tr><th>Product</th><th>Market Signal</th><th>Fit</th><th>Build Order</th></tr>
<tr><td>Adaptive UI dashboard</td><td>Context-aware developer surfaces are emerging category</td><td><span class="pill live">Strong</span></td><td>P0</td></tr>
<tr><td>Agent Task Harness</td><td>Deterministic multi-agent orchestration is foundational</td><td><span class="pill live">Strong</span></td><td>P1</td></tr>
<tr><td>Agent Memory Store</td><td>Cross-session memory is table stakes for useful agents</td><td><span class="pill live">Strong</span></td><td>P1</td></tr>
<tr><td>PR Review Agent</td><td>Automated review reduces human load</td><td><span class="pill live">Strong</span></td><td>P1</td></tr>
<tr><td>Repo Scaffolder Agent</td><td>NL project generation lowers onboarding friction</td><td><span class="pill wip">Medium</span></td><td>P2</td></tr>
<tr><td>Hou3 creative pipeline</td><td>Launch docs/content automation</td><td><span class="pill wip">Medium</span></td><td>P2</td></tr>
<tr><td>Gitea Pages site</td><td>Public lab landing page</td><td><span class="pill blocked">Medium</span></td><td>Blocked</td></tr>
<tr><td>Kanban-to-issue sync</td><td>Single pane of glass</td><td><span class="pill wip">Medium</span></td><td>Wired</td></tr>
</table>
</section>
<hr class="rule" />
<section class="grid grid-3">
<div class="card">
<div class="phase">Phase A — 0–48h</div>
<h2>Close the Loop</h2>
<ul>
<li>Ship adaptive dashboard panels from #8–#13</li>
<li>Wire Hou3 output → issues/PRs as real comments</li>
<li>Run first full autonomous cycle: branch, impl, PR, self-review, merge</li>
</ul>
</div>
<div class="card">
<div class="phase">Phase B — 48h–2w</div>
<h2>Harden</h2>
<ul>
<li>Fill test suites in dashboard + agent-todo-tracker</li>
<li>Automate token rotation via cron/Hermes job</li>
<li>Profile memory usage before adding more workers</li>
</ul>
</div>
<div class="card">
<div class="phase">Phase C — 2w+</div>
<h2>Scale</h2>
<ul>
<li>Multi-repo issue queue across <span class="kbd">stackchain/*</span></li>
<li>Unique staging targets per RC</li>
<li>Separate Hou3 creative queue from code queue</li>
</ul>
</div>
</section>
<hr class="rule" />
<div class="card">
<h2>Human Gates</h2>
<table>
<tr><th>Human Action</th><th>Trigger</th><th>What to do</th></tr>
<tr><td>Prototype review</td><td>PR includes preview link</td><td>Click, test, comment feedback</td></tr>
<tr><td>RC approval</td><td>Automated tests pass, draft release created</td><td>Verify locally, merge release PR</td></tr>
<tr><td>Pages handoff</td><td>Issue #14 is `blocked`</td><td>Enable Gitea Pages in UI; confirm URL</td></tr>
<tr><td>3 consecutive failed reviews</td><td>Auto-pause in loop</td><td>Surface in issue, triage, decide path</td></tr>
</table>
</div>
<footer style="margin-top:20px;color:#6b7280;font-size:12px;">
Source of truth: Gitea issues/PRs. Hermes kanban is mirror-only. No human devops required unless explicitly gated.
</footer>
</div>
</body>
</html>

84
docs/agent-engineering-report.md Normal file
View File

@ -0,0 +1,84 @@
# Stackchain AI Lab — Agent Engineering Report
**Audience:** agent engineers
**Date:** 2026-07-08
**Status:** Operations active, prototypes shipping, release candidates pending human test only
---
## 1. Current State — What We Have Built
| Layer | Artifact | Status | Evidence |
|---|---|---|---|
| **Infra** | Gitea 1.22.0 on VPS, Caddy-free routing | Live | `https://forge.alexanderwhitestone.com/git/` |
| **Org** | `stackchain` org, 4 repos, 5 users | Live | Repos: `hackathon`, `dashboard`, `agent-todo-tracker`, `project-template` |
| **Auth** | Least-privilege tokens per agent/user | Live | `timmy` org-admin, `turdbot` bot, admin CLI |
| **Pipeline** | CI + RC workflows in `.gitea/workflows` | Live | Push to main auto-tags + drafts RC |
| **Loop** | Autonomous issue→PR→review→merge/no-spam | Locked | Stale 72h, close +24h, velocity `#Velocity` |
| **Agent** | `agent-todo-tracker` CLI shipped | Done | `init/create/list/update/close`, SQLite storage |
| **Kanban** | Hermes board + Gitea label sync | Wired | `scripts/gitea_sync.py` |
| **Creative** | Hou3 dispatcher profile (Tencent Hy3) | Active | Assigned to #16/#17/#18, composing deliverables |
---
## 2. Operational Constraints — Read This First
- **No Caddy changes** for Gitea work. Period.
- **No human devops.** Humans only: review prototype, test RC, approve ship.
- **Cached config:** `/etc/gitea/app.ini` `ROOT_URL=https://forge.alexanderwhitestone.com/git/`
- **Asset path:** `/var/lib/gitea/public/assets/` — verified exists
- **Pages status:** Repo Pages API returns 404; enablement gated on human config handoff
- **Dupe cleanup:** `john`/`JohnGalt` removed; `john52galt` retained
- **Admin roster:** `rockachopa`, `timmy`, `grepples`, `john52galt`
---
## 3. Market Fit Matrix — What We Can Build Next
| Idea | Market Signal | Fit | Build Order |
|---|---|---|---|
| **Adaptive UI dashboard** | Developers want intelligent, context-aware interfaces | Strong | P0 — already scoped in #8, needs fleshed panels |
| **Agent Task Harness** | Multi-agent orchestration is table stakes for agentic startups | Strong | P1 — deterministic routing, retry, circuit break |
| **Agent Memory Store** | Every agent needs persistent memory across sessions | Strong | P1 — shared KV store, embeddings optional |
| **PR Review Agent** | Automated code review reduces human review load | Strong | P1 — inline comments, label-based auto-merge |
| **Repo Scaffolder Agent** | Natural-language project generation lowers onboarding friction | Medium | P2 — templates + agent-driven file gen |
| **Hou3 creative pipeline** | Marketing/docs automation for launch velocity | Medium | P2 — release notes, overlay variants, README polish |
| **Gitea Pages site** | Public landing page for the lab | Medium | Blocked on Pages enablement |
| **Kanban-to-issue sync** | Single pane of glass for ops | Medium | Wired but untested at scale |
---
## 4. Recommended Sequencing — Take It to the Next Level
### Phase A — Close the Loop (0–48h)
1. **Ship dashboard panels.** Turn the scaffold in `stackchain-dashboard` into a clickable, adaptive UI. Map panels to concrete Gitea views: review queue, issue triage, repo health.
2. **Wire Hou3 output to PRs/issues.** Move from “drafting” to “posting review comments” on assigned issues. Close #16, #17, #18 with actual deliverables.
3. **Run the first full autonomous cycle.** Pick one P1 issue, branch it, implement, open PR, self-review, merge. Prove the loop without spam.
### Phase B — Harden (48h–2w)
4. **Add tests.** The dashboard and `agent-todo-tracker` need real pytest suites. CI already runs them — fill the gap.
5. **Token rotation cadence.** Automate via cron or a Hermes job. Don’t rely on manual rotation.
6. **Resource audit.** 8GB RAM VPS. Model: Gitea + Caddy + N agents + dashboard. Profile before adding more workers.
### Phase C — Scale (2w+)
7. **Multi-repo velocity.** Queue issues across `stackchain/*`, not just `hackathon`.
8. **External preview URLs.** Each RC gets a unique staging target. Humans click, test, approve.
9. **Hou3 specialization.** Split creative dispatch into its own queue with different acceptance criteria than code agents.
---
## 5. Risk Register
| Risk | Likelihood | Mitigation |
|---|---|---|
| Gitea Pages never enables via API | Medium | Surface as explicit human handoff in #14; do not block other work |
| 8GB RAM exhaustion | Medium | Add memory watchdog; serialize worker starts |
| Duplicate accounts / auth drift | Low | Single admin path through Timmy; audit weekly |
| CI workflow YAML drift | Medium | One canonical workflow source; no mirroring |
| Hou3 repeats itself / spams comments | Medium | Seen-state tracking in `dispatch.state`; max-comment guard |
---
## 6. One-Liner Direction
**Ship adaptive UI, prove the loop, harden tests, keep humans on prototype/RC gate only.**