commit 6c359d793aebb3f17114c697ac76e2e600f0412a Author: timmy Date: Sun Jul 12 12:11:10 2026 +0000 chore: refresh stackchain-hackathon tracking files diff --git a/REPORT.md b/REPORT.md new file mode 100644 index 0000000..8c25710 --- /dev/null +++ b/REPORT.md @@ -0,0 +1,101 @@ +# Agent Engineering Report — 2026-07-08 + +**Audience:** agent engineers +**Status:** Operations active, prototypes shipping, release candidates pending human test only + +--- + +## Current State + +**Infra:** Gitea 1.22.0 on VPS, Caddy-free routing +**Public URL:** +**Org:** [stackchain](https://forge.alexanderwhitestone.com/git/org/stackchain) +**Repos:** 4 active (`hackathon`, `dashboard`, `agent-todo-tracker`, `project-template`) +**Active users:** 5 (rockachopa, timmy, grepples, john52galt, turdbot) — 4 admins, 1 bot user +**Pipeline:** CI + RC workflows in `.gitea/workflows` — pushed and live +**Loop:** Issue → PR → review → merge/no-spam; stale 72h / close +24h; velocity in `#Velocity` +**Creative agent:** Hou3 profile (Tencent Hy3) active; assigned to #16, #17, #18 + +--- + +## Operational Constraints + +| Constraint | Rule | +|---|---| +| Caddy | No changes for Gitea work | +| Human touchpoints | Prototype review + RC test only | +| Config | `ROOT_URL=https://forge.alexanderwhitestone.com/git/` | +| Assets | `/var/lib/gitea/public/assets/` verified present | +| Pages API | Returns 404; enablement gated on human config handoff | +| Cleanup | Dupe users removed, admins promoted | + +--- + +## Queue Snapshot + +- **Open issues:** 19 items in `stackchain-hackathon` +- **P0/P1:** Pages enablement (blocked on human handoff), #8 adaptive UI, #10 context, #11 engine, #12 frontend panels +- **P2:** #13 cache, #5 agent-todo, #6 scaffolder +- **Creative:** #16 README, #17 overlays, #18 release notes +- **Open PRs:** 0 +- **Hou3:** Actively composing deliverable drafts + +--- + +## Risk Register + +| Risk | Likelihood | Mitigation | +|---|---|---| +| Gitea Pages auth | Medium | Surface as explicit handoff in #14; do not block | +| 8GB RAM exhaustion | Medium | Watchdog + serialize worker starts | +| Auth drift | Low | Single admin path through Timmy; audit weekly | +| Workflow drift | Medium | One canonical workflow source | +| Hou3 spam | Low | Seen-state tracking + max-comment guard | + +--- + +## Market Fit Matrix + +| Product | Market Signal | Fit | Build Order | +|---|---|---|---| +| Adaptive UI dashboard | Context-aware developer surfaces are emerging category | Strong | P0 | +| Agent Task Harness | Deterministic multi-agent orchestration is foundational | Strong | P1 | +| Agent Memory Store | Cross-session memory is table stakes for useful agents | Strong | P1 | +| PR Review Agent | Automated review reduces human load | Strong | P1 | +| Repo Scaffolder Agent | NL project generation lowers onboarding friction | Medium | P2 | +| Hou3 creative pipeline | Launch docs/content automation | Medium | P2 | +| Kanban-to-issue sync | Single pane of glass | Medium | Wired | + +--- + +## Recommended Sequencing + +### Phase A — 0–48h +1. Ship adaptive dashboard panels from #8–#13 +2. Wire Hou3 output to issues/PRs as real comments +3. Run first full autonomous cycle: branch, implement, PR, self-review, merge + +### Phase B — 48h–2w +4. Fill test suites in dashboard + agent-todo-tracker +5. Automate token rotation via cron/Hermes job +6. Profile memory usage before adding more workers + +### Phase C — 2w+ +7. Multi-repo issue queue across `stackchain/*` +8. Unique staging targets per RC +9. Separate Hou3 creative queue from code queue + +--- + +## Human Gates (Only Human Actions Needed) + +| Human Action | Trigger | What to Do | +|---|---|---| +| Prototype review | PR includes preview link | Click, test, comment feedback | +| RC approval | Automated tests pass, draft release created | Verify locally, merge release PR | +| Pages handoff | Issue #14 is `blocked` | Enable Gitea Pages in UI; confirm URL | +| 3 consecutive failed reviews | Auto-pause in loop | Surface in issue, triage, decide path | + +--- + +**One-liner direction:** Ship adaptive UI, prove the loop, harden tests, keep humans on prototype/RC gate only. diff --git a/docs/agent-engineering-report.html b/docs/agent-engineering-report.html new file mode 100644 index 0000000..09f0a9b --- /dev/null +++ b/docs/agent-engineering-report.html @@ -0,0 +1,184 @@ + + + + + +Stackchain AI Lab — Agent Engineering Report + + + +
+
+
+

Stackchain AI Lab — Agent Engineering Report

+
Audience: agent engineers · 2026-07-08 · Source of truth: Gitea
+
+
Operations active
+
+ +
+
+

Current State

+ + + + + + + + + +
InfraGitea 1.22.0, Caddy-free routing
Public URLforge.alexanderwhitestone.com/git/
Orgstackchain
Repos4 active (`hackathon`, `dashboard`, `agent-todo-tracker`, `project-template`)
Active users5 (2 admins onboarded via CLI + 2 promoted via DB + bot)
PipelineCI + RC workflows pushed to mains
LoopIssue → PR → review → merge/no-spam, stale/blocked handled
Creative agentHou3 profile active on Tencent Hy3
+
+ +
+

Stackchain Dashboard

+ + + + + + + +
Repostackchain/stackchain-dashboard
BackendFastAPI context endpoint + suggestion engine
FrontendAdaptive SPA shell with 3-column layout
KanbanHermes board + label sync script wired
Issues#9 epic, #10 context, #11 engine, #12 panels, #13 cache
StatusWIP Backend scaffold shipped
+
+ +
+

Queue Snapshot

+ + + + + + + + +
Open issues19 items in `stackchain-hackathon`
P0/P1P0 Pages enablement (blocked on human handoff)
P1#8 Adaptive UI, #10 context, #11 engine, #12 frontend
P2#13 cache, #5 agent-todo, #6 scaffolder
Creative#16 README, #17 overlays, #18 release notes
Open PRs0
Hou3Actively composing deliverable drafts
+
+
+ +
+ +
+
+

Operational Constraints

+ + + + + + + +
CaddyNo changes for Gitea work
Human touchpointsPrototype review + RC test only
Config`ROOT_URL=https://forge.alexanderwhitestone.com/git/`
Assets`/var/lib/gitea/public/assets/` verified present
Pages APIReturns 404; enablement gated
Cleanup doneDupe users removed, admins promoted
+
+ +
+

Risk Register

+ + + + + + +
Gitea Pages authMediumSurface as handoff in #14
MemoryMediumWatchdog + serialize workers
Auth driftLowSingle admin path, weekly audit
Workflow driftMediumOne canonical workflow source
Hou3 spamLowSeen-state + max-comment guard
+
+
+ +
+ +
+

Market Fit Matrix — What We Can Build

+ + + + + + + + + + +
ProductMarket SignalFitBuild Order
Adaptive UI dashboardContext-aware developer surfaces are emerging categoryStrongP0
Agent Task HarnessDeterministic multi-agent orchestration is foundationalStrongP1
Agent Memory StoreCross-session memory is table stakes for useful agentsStrongP1
PR Review AgentAutomated review reduces human loadStrongP1
Repo Scaffolder AgentNL project generation lowers onboarding frictionMediumP2
Hou3 creative pipelineLaunch docs/content automationMediumP2
Gitea Pages sitePublic lab landing pageMediumBlocked
Kanban-to-issue syncSingle pane of glassMediumWired
+
+ +
+ +
+
+
Phase A — 0–48h
+

Close the Loop

+
    +
  • Ship adaptive dashboard panels from #8–#13
    • +
  • Wire Hou3 output → issues/PRs as real comments
    • +
  • Run first full autonomous cycle: branch, impl, PR, self-review, merge
    • +
+
+
+
Phase B — 48h–2w
+

Harden

+
    +
  • Fill test suites in dashboard + agent-todo-tracker
    • +
  • Automate token rotation via cron/Hermes job
    • +
  • Profile memory usage before adding more workers
    • +
+
+
+
Phase C — 2w+
+

Scale

+
    +
  • Multi-repo issue queue across stackchain/*
    • +
  • Unique staging targets per RC
    • +
  • Separate Hou3 creative queue from code queue
    • +
+
+
+ +
+ +
+

Human Gates

+ + + + + + +
Human ActionTriggerWhat to do
Prototype reviewPR includes preview linkClick, test, comment feedback
RC approvalAutomated tests pass, draft release createdVerify locally, merge release PR
Pages handoffIssue #14 is `blocked`Enable Gitea Pages in UI; confirm URL
3 consecutive failed reviewsAuto-pause in loopSurface in issue, triage, decide path
+
+ +
+ Source of truth: Gitea issues/PRs. Hermes kanban is mirror-only. No human devops required unless explicitly gated. +
+
+ + diff --git a/docs/agent-engineering-report.md b/docs/agent-engineering-report.md new file mode 100644 index 0000000..d865391 --- /dev/null +++ b/docs/agent-engineering-report.md @@ -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.** diff --git a/docs/engineering-org-protocol.md b/docs/engineering-org-protocol.md new file mode 100644 index 0000000..2365ab7 --- /dev/null +++ b/docs/engineering-org-protocol.md @@ -0,0 +1,34 @@ +# Engineering Org Protocol + +## Intake (Human → Org) +User says: "We want [requirement]." +1. Agent breaks requirement into Epic + child issues. +2. Each issue gets labels (`P0`/`P1`/`P2`, type: `feature`, `bug`, `chore`, `docs`). +3. Each issue gets an assignee based on agent roster. +4. Epic links issues via Milestone. + +## Execution (Org → Ship) +- Dispatch loop polls assigned issues. +- Agent acknowledges, branches `/-`, implements, opens PR. +- PR references parent issue. +- CI runs automatically. +- Self-review before merge: lint, tests, diff size, issue linkage. +- Auto-merge only if: approval flag set AND low-risk AND human not previously blocked. + +## Release Cycle +- Main branch = production-ready. +- CI auto-tags RC on merge. +- Human test RC in staging. +- Human says “ship” or “rework.” +- Agents do not push to production; humans approve releases. + +## Agent Roster +- `timmy` — admin, orchestration, dispatch +- `hou3` — creative, docs, UI copy, release notes +- `turdbot` — integration, API, CI pipelines +- `vincent` — frontend/backend implementation + +## Human Gates +- Prototype review (click preview, comment) +- RC approval (test, merge release) +- Blocked/paused workflows (3 failed reviews)