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
+
+ + +
+ + 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.**