Fold idea-workshop into /new-project; add placement reference
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).
This commit is contained in:
@@ -0,0 +1,92 @@
|
||||
# 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.md` item "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.
|
||||
Reference in New Issue
Block a user