goal.md
Rama main · réplica de lectura del repositorio original.
# Goal: HomeAIOps to Production-Ready, Then Invert the Workflow
> **Superseded 2026-07-06 — historical record only.** This brief drove the
> HomeAIOps / langgraph-agents buildout. The langgraph-agents fleet was
> decommissioned 2026-07-06 ("no value delivered"); Stages 2–3 below describe
> machinery that no longer exists in the cluster. Retained as preserved intent.
> The companion routing artifact (`docs/src/routing_policy.md`) was likewise
> removed in the 2026-09 documentation cleanup.
## Context
`CLAUDE.md` is the canonical context for this work. Read it first. It defines
the architecture, the pipeline inputs, the workflows, what "working" means, and
the DoD references this prompt points at.
Conflict resolution order:
- If this prompt and `CLAUDE.md` disagree on **facts about the system**,
`CLAUDE.md` wins.
- If this prompt and `CLAUDE.md` disagree on **stage scoping or rules of
engagement**, this prompt wins.
- If the **repo** and `CLAUDE.md` disagree, the repo wins. Flag the drift and
update `CLAUDE.md` as part of the relevant PR.
Also read existing `TODO.md`, prior memories, and inline `TODO(homeaiops):`
comments. Treat them as authoritative state on what's done and what's pending.
## Why this run exists
We've been going two steps forward, one back. The point of this run is to break
that pattern. Verify before you declare done. Keep state honest as you go.
Don't skip the gates between stages.
## Rules of engagement (apply to all stages)
- One PR per logical concern. Max 3 PRs open concurrently.
- PR → wait for green CI → rebase on main if needed → merge.
- No opportunistic refactors, dependency bumps, or scope creep. If you find
something out of scope that's broken, file an issue, don't fix it.
- Bug triage: P0 (blocks current stage DoD) fix now. P1 file an issue and
continue. P2 add to `TODO.md`.
- If CI is red and the cause isn't obvious flakiness, stop and tell me.
- Update `TODO.md`, memories, inline `TODO`s, and `CLAUDE.md` as you close
items. A rich context doc that's drifted from reality is worse than a sparse
one — treat `CLAUDE.md` maintenance as part of the work, not an afterthought.
- For each verification, paste the actual output in the PR. No "looks good" —
show the green.
- Parallelize aggressively *within* a stage (independent components,
independent PRs). Do not parallelize *across* stages — the gates exist
because scaffolding a later stage while an earlier stage is flaky is the
exact pattern we're breaking.
- When in doubt about scope, intent, or whether something counts as "done" —
ask. A two-line clarification beats a two-day detour.
---
## Stage 1 — Stabilize
Audit every HomeAIOps component top-to-bottom against the DoD documented in
`CLAUDE.md` and the repo. For each component: run the documented verification,
paste evidence in the PR, fix what's broken.
### Definition of done
- [ ] All HomeAIOps components pass their documented health checks
- [ ] End-to-end smoke test passes: task in → result out
- [ ] Survives a `flux suspend` / `resume` cycle on the relevant kustomizations
without manual intervention
- [ ] Survives a pod-level restart of each component
- [ ] Runbooks exist in `docs/runbooks/` for the top failure modes hit while
stabilizing
### Gate 1
Stop here. Post the smoke test output and the runbook list. Wait for my
approval before starting Stage 2.
---
## Stage 2 — Migrate workflows onto HomeAIOps
### Capability gap analysis (do this first, before building)
Produce a written gap analysis covering:
- What my current Claude Code workflow provides (todos, task dispatch, session
history, anything else surfaced in memory or `CLAUDE.md`)
- What HomeAIOps provides today
- The gap, prioritized
The CLI is **my** primary interface to the pipeline, replacing my current
Claude Code workflow. It is **not** the pipeline's only input — the repo
already defines other inputs that feed the same task store and execution path.
Treat the CLI as a peer to those, not a replacement for them. Shared concerns
(task schema, store, dispatch, result handling) belong in the pipeline; the
CLI is a thin client on top.
In the gap analysis, confirm: which existing inputs feed the pipeline today,
what schema/contract they use, and where the CLI plugs into that same
contract. If the contract is implicit or inconsistent across inputs, making
it explicit is part of Stage 2 — but as a deliberate sub-task, not a drive-by
refactor.
Show me the gap analysis before you start closing it.
### Then close the gaps
- Build/finish the terminal CLI that submits tasks to the local AI pipeline.
Installed on `$PATH`, `--help` works, core commands documented.
- Move todo management out of Claude Code into HomeAIOps' own store. Claude
Code becomes a consumer, not the store.
- Each capability moves in its own PR with a documented rollback path.
### Definition of done
- [ ] CLI is the primary interface for submitting tasks to local AI
- [ ] Todos live in HomeAIOps; Claude Code is a consumer, not the store
- [ ] Existing non-CLI inputs still work end-to-end (verified, not assumed)
after the CLI lands
- [ ] One full day of dogfooding without falling back to Claude Code for the
primary task flow
### Gate 2
Stop here. Post the day-of-dogfooding log. Wait for my approval before
starting Stage 3.
---
## Stage 3 — Invert: local-first with Claude escalation
Today I drive Claude Code, and Claude sometimes calls local infra. Target:
I drive HomeAIOps, and HomeAIOps decides when to escalate to Claude.
Routing, escalation, provenance, and cost visibility apply to **all** inputs
into the pipeline, not just CLI-submitted tasks. The routing policy is
input-agnostic: a task is a task regardless of whether it arrived via CLI or
any other input defined in the repo. Provenance records the input source
alongside the execution target so I can see, per input, what's running local
vs. escalating.
### Required pieces
- **Routing policy.** Version-controlled file in the repo that decides
local vs. escalate based on explicit rules (task type, model capability,
context size, sensitivity). No learned router yet — explicit rules first.
Changing the file changes behavior.
- **Escalation client.** HomeAIOps calls Claude as a subordinate worker. Use
Claude Code in headless mode for tool-using/coding tasks; use the raw
Anthropic API for classification, summarization, drafting. Document the
rule for which is used when.
- **Provenance.** Every task result records where it ran (local model +
version, or Claude + model string) and which input it arrived from.
- **Fallback on failure.** If local execution fails or returns low
confidence, auto-escalate with the failure context attached — don't restart
from a fresh prompt.
- **Cost/usage visibility.** CLI subcommand showing local vs. escalated task
counts and Claude spend over the last N days. Without this, "local-first"
silently becomes "Claude-first with extra steps."
- **Guardrail against silent Claude-creep.** Budget threshold; if escalation
rate or spend crosses it, surface a warning. (This is the failure mode I'm
most worried about — drift toward escalating everything.)
### Definition of done
- [ ] I issue tasks to the CLI by default for one full week (wall-clock; the
week ends when I confirm it, not when you think the work is done)
- [ ] At least one task type round-trips local → escalate → result with no
intervention from me
- [ ] Routing policy file is the single source of truth; behavior changes when
I edit it
- [ ] Escalation and provenance work uniformly across all pipeline inputs, not
just CLI
- [ ] Escalation rate and Claude spend are visible from the CLI
- [ ] Runbook exists for "local infra is down, fall back to Claude Code
directly"
---
## Final note
If something in this prompt contradicts what you find in `CLAUDE.md` or the
repo, apply the conflict resolution order at the top and tell me what you
found. Don't paper over it.