Keysat
908d96a6e5
Harvest the retired idea-workshop skill into the current new-project flow: - form-factor gate (is this even a standalone repo, or a feature/skill/agent of something that exists? bail + reroute if so) - worth-building gate at sign-off (build effort + ongoing tax -> BUILD/PARK/ADOPT) - placement step that walks the new guides/placement.md - falsifiable-exit substance rule and a posture section - architectural decisions land in the new repo's AGENTS.md ## Decisions section, absorbing the old DECISIONS.md function (no separate ADR file) Add guides/placement.md (ported from the skill) and point how-i-work.md at it. Its infra facts are UNVERIFIED (one-shot from chat history) and flagged for a review pass with me (ROADMAP item 7).
5.3 KiB
Placement guide — where should a new project live?
Reference doc for the "where does this run, which model, what data layer?" question. It
encodes two things: a stable decision sequence (rarely changes) and a set of
infrastructure facts (go stale — keep them current). /new-project walks this against
every new idea (guides/new-project.md, Phase 2); how-i-work.md points here so any
session placing a project consults it rather than guessing.
⚠️ The infrastructure facts below are UNVERIFIED. They were generated one-shot from chat history and have not been confirmed against the actual setup. Treat every fact in the next section as provisional until reviewed and corrected with the user — see the standards
ROADMAP.mditem "Verify & correct the placement guide." The decision sequence and the substance rule are sound regardless; it's the specific service/model/network facts that need a pass.
Infrastructure facts (PROVISIONAL — last generated June 2026, not yet verified)
Start9 server — StartOS 0.4.x. Hosts long-running services as s9pk packages or plain containers. Believed running: Gitea (version control for LLM-assisted projects — the default repo home), Nextcloud (general file backup), Home Assistant (Container install), Electrs, Core Lightning + RTL, Open WebUI as the sovereign chat/session layer.
Inference — Two NVIDIA DGX Sparks behind the Spark Control HTTP gateway on the LAN, serving Qwen3 (vLLM, OpenAI-compatible endpoints) as the primary production backend. Kokoro for TTS. bge-m3 for embeddings. Treated as real production capacity — existing apps (call transcription/recap, CRM pipeline, email-summary agent) already depend on it.
Data layer defaults — SQLite for structured data; Qdrant + bge-m3 when semantic retrieval is needed; flat files when that's the honest answer.
Sovereignty boundary (standing rule) — Anything touching sensitive investor, LP, or portfolio data uses local models only, via the Spark gateway. Frontier APIs (Anthropic etc.) are fine for everything else. Non-negotiable per project; the only question is which side of the line the project's data sits on.
Access — WireGuard split-tunnel from macOS to the home subnet (runs alongside Proton VPN). iOS is constrained to a single VPN tunnel; workarounds are Tor onion addresses or a merged WireGuard config. So "reachable from phone" is a real design constraint, not a footnote.
Dev machine — macOS with Claude Code. One-off and personal CLI tools live here happily.
Decision sequence (stable)
Walk these in order; each answer narrows the next.
1. Sensitivity. Does the project ingest, store, or send investor/LP/portfolio data to a model? If yes: local inference mandatory, hosting on the home subnet strongly preferred, and AGENTS.md must state the constraint explicitly so a coding session never "helpfully" wires in a frontier API call with payload data.
2. Runtime shape. One-shot CLI / scheduled job / long-running service / interactive UI?
- One-shot or personal CLI → Mac. Don't deploy what doesn't need deploying.
- Scheduled job → Mac launchd if it only matters while the laptop lives; Start9 if it must run unattended 24/7.
- Long-running service, or anything other devices/family/agents need to reach → Start9.
3. If Start9: s9pk or plain container? s9pk earns its packaging cost when the service wants the StartOS lifecycle — backups, health checks, dependency management, clean updates — or could plausibly be published for others. Plain container (or script) wins for experiments, single-user glue, and anything still changing shape weekly. Default for prototypes: container now, promote to s9pk if it survives and stabilizes. Packaging for 0.4.x is nontrivial; don't pay it on spec.
4. Model routing. Default to local Qwen3 via the Spark gateway when the sovereignty boundary applies, when latency/cost favor local, or when the task is well within Qwen3's capability. Route to frontier (Claude API) for hard reasoning on non-sensitive data. Record the chosen endpoint in AGENTS.md so sessions don't guess.
5. Data layer. SQLite unless there's a reason; Qdrant + bge-m3 when retrieval quality is the product; flat files for logs and artifacts. Name Qdrant collections per-project to avoid the shared-collection mess.
6. Interface. CLI first unless the UI is the product. If it must be reachable from the phone, remember the iOS single-tunnel constraint — decide up front whether that means onion address, merged WireGuard config, or "Mac-only is fine."
7. Repo home. Gitea on Start9. Always — even for parked-then-revived ideas, so history accumulates in one place.
Phase-exit criteria — the substance rule
Phase exits are falsifiable substance: numbers and demonstrable behavior. "46/46 tests pass," "recap generated from a real 40-minute call in under 2 minutes," "correct doc in top-3 for 9/10 canned queries." If the criterion can't fail, it isn't a criterion.
Maintenance
The infrastructure facts section is the part that goes stale. When the infra changes — new hardware, StartOS version, model lineup, network setup, a service added or retired — update that section here rather than working around it in conversation. The decision sequence and the substance rule rarely change.