diff --git a/.opencode/agents/poc-specialist.md b/.opencode/agents/poc-specialist.md index f5fae5f..3990f9d 100644 --- a/.opencode/agents/poc-specialist.md +++ b/.opencode/agents/poc-specialist.md @@ -1,5 +1,5 @@ --- -description: Create proof-of-concepts to validate technical approaches. Works in isolated research worktrees to test hypotheses before production implementation. +description: Create proof-of-concepts to validate technical approaches. Works in branch mode (research branch on repo code) or standalone mode (scratch project outside the repo) depending on whether the hypothesis touches repo code. mode: primary temperature: 0.3 --- @@ -7,7 +7,26 @@ temperature: 0.3 You are the **POC Specialist**, creating proof-of-concepts to validate technical approaches. -## Your Environment +## POC Modes — determine yours before writing anything + +POC code never merges to main. POCs are exploration tools with relaxed +constraints (comments and unwrap are acceptable), and their source is +disposable once findings are recorded. Two modes: + +- **Branch mode** — the hypothesis builds on code in this repo. You are in + a research worktree on branch `research/`; the open-coordinator + plugin auto-injects your working directory. Findings are merged into + `docs/research/` on main and the branch is dropped — the POC code itself + does not merge. +- **Standalone mode** — the hypothesis is independent of repo code. Work in + a scratch project at `/workspace/` (create it; do not put it in + any alkdev repo). Write findings directly into `docs/research/` on main + when done. + +The spawn prompt or task file tells you which mode. If it doesn't, ask the +coordinator — don't guess. + +## Your Environment (branch mode) **You are in a research worktree.** The open-coordinator plugin auto-injects your working directory for all bash commands — you do NOT need to specify @@ -33,6 +52,13 @@ worktree({action: "status"}) → Show worktree git status **If mismatch → Safe Exit immediately** +## Your Environment (standalone mode) + +There is no worktree tool mapping. Your working directory is the scratch +project root (e.g. `/workspace/alkgit-poc1`); create it with `cargo new` or +similar if it doesn't exist. Do not touch files outside that directory and +the main repo's `docs/research/` (findings only). + ## The `worktree` Tool (Implementation Agent) As a spawned agent, you have access to a limited set of worktree operations: @@ -211,4 +237,6 @@ worktree({action: "notify", args: {message: "POC completed: ", level: " 2. **Document ruthlessly** - findings are the deliverable 3. **Timebox strictly** - abandon if taking too long 4. **Honest assessment** - don't make it work at all costs -5. **Research worktree** - never touch files outside `.worktrees/research/` +5. **Stay in your lane** - branch mode: never touch files outside your + research worktree; standalone mode: never touch files outside your + scratch project and the main repo's `docs/research/` diff --git a/AGENTS.md b/AGENTS.md index 61a1214..efe24d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -177,8 +177,12 @@ If feature flags are added, also run `cargo test --all-features` and The project is in **SDD phase 0** (exploration) — see `docs/sdd_process.md` and `docs/research/README.md`. There is no architecture yet (`docs/architecture/` is empty; ADR numbering starts at -001 when phase 1 begins). POCs land under `.worktrees/research/` or as -scratch dirs; their findings go into `docs/research/`. Until phase 1 +001 when phase 1 begins). POC code never merges to main — two modes: +branch mode (POC builds on repo code; git branch, findings merged into +research docs, branch dropped) or standalone mode (POC independent of +repo code; scratch project at `/workspace/`). POCs have relaxed +constraints (comments/unwrap acceptable) — they are exploration tools, +not production code. Until phase 1 produces ADRs, "the architecture says" has no referent — cite `docs/research/` docs instead. diff --git a/docs/research/pocs.md b/docs/research/pocs.md index 5227a0d..ce21553 100644 --- a/docs/research/pocs.md +++ b/docs/research/pocs.md @@ -1,8 +1,24 @@ # alkgit POC Plan -POCs live in research worktrees (`.worktrees/research//`) per -sdd_process phase 0, or as scratch experiments outside the main workspace -tree if a worktree isn't available yet. Each POC records: hypothesis, +## POC modes + +POCs are not production code — fewer constraints (comments, unwrap, error +taxonomy are all relaxed), and their code never merges to main. Two modes, +chosen by whether the POC touches code in this repo: + +- **Branch mode** (POC depends on alkgit code in the repo): create a git + branch off main, do the work there, then **merge the findings into the + research docs** on main and drop the branch — the POC code itself does + not merge. +- **Standalone mode** (POC is independent of alkgit code): a scratch crate + or project at `/workspace/` (e.g. `/workspace/alkgit-poc1`), + outside the repo entirely. Findings are written directly into + `docs/research/` on main. + +In both modes the deliverable on main is the findings write-up, not the +POC source. POC source is disposable once findings are recorded. + +Each POC records: hypothesis, method, result (proceed/pivot/block), and what it changes in the research docs. @@ -68,4 +84,13 @@ for receive-pack sizing. POC-1 first (the BiStream/packetline fit is the load-bearing assumption). POC-2 next (the crux of fetch). POC-3 last (http shape). Each POC updates -the corresponding research doc with results and a proceed/pivot/block note. \ No newline at end of file +the corresponding research doc with results and a proceed/pivot/block note. + +## Modes applied to these POCs + +- POC-1, POC-2: **standalone mode** — nothing in the alkgit repo exists to + build on yet; run as `/workspace/alkgit-poc1` and `/workspace/alkgit-poc2`. + (If POC-1's bridge turns out to want the workspace deps, it can flip to + branch mode on the repo instead — decide before writing, not after.) +- POC-3: **branch mode** — it exercises alkhttp wiring against this repo's + skeleton; findings merge into `alk-stack.md`, branch is dropped after. \ No newline at end of file diff --git a/docs/sdd_process.md b/docs/sdd_process.md index b81e306..e3c1867 100644 --- a/docs/sdd_process.md +++ b/docs/sdd_process.md @@ -33,10 +33,19 @@ problems need investigation. 1. Capture vision and guiding principles 2. Research Specialist investigates options (`docs/research/` or external) -3. POC Specialist validates promising approaches (`.worktrees/research/`) +3. POC Specialist validates promising approaches 4. Document learnings 5. Converge on recommended approach +**POC placement (two modes)** — POC code never merges to main; the +deliverable is the findings write-up: + +- **Branch mode** (POC builds on code in this repo): git branch off main, + work there, merge findings into research docs, drop the branch. +- **Standalone mode** (POC independent of this repo's code): scratch + project at `/workspace/`, outside the repo. Findings go into + `docs/research/` on main directly. + **Output**: Clear understanding of WHAT to build and WHY, with validated approaches @@ -89,7 +98,10 @@ WHAT, ADRs explain WHY, open questions track what's unresolved. 2. Coordinator spawns worktrees + sessions (via `worktree({action: "spawn", ...})` or hub `coord.spawn` when available) - Feature work: `.worktrees/feat//` → Implementation Specialist - - Research POCs: `.worktrees/research//` → POC Specialist + - Research POCs building on repo code: `.worktrees/research//` + → POC Specialist (branch mode) + - Research POCs independent of repo code: standalone scratch project at + `/workspace/` → POC Specialist (standalone mode) 3. Coordinator injects task context into each session 4. Agents execute tasks with self-verification 5. On completion: agent notifies coordinator, updates task status, commits to @@ -312,9 +324,11 @@ limited set (current, notify, status). No mode toggle required. **Responsibility**: Create proof-of-concepts to validate technical approaches before production implementation. -**Mode**: Primary (works in isolated research worktree) +**Mode**: Primary (branch mode: isolated research worktree; standalone +mode: scratch project outside the repo) -**Worktree Location**: `.worktrees/research//` +**Worktree Location**: `.worktrees/research//` (branch mode) or +`/workspace/` (standalone mode) **Tools**: @@ -324,8 +338,10 @@ before production implementation. **Key Behaviors**: - Create minimal POCs to validate hypotheses -- Work in isolated research worktrees -- Document findings and recommendations +- Branch mode: work in isolated research worktrees; standalone mode: work + in the scratch project only +- Document findings and recommendations (findings are the deliverable — + POC source is disposable and never merges to main) - Timebox strictly - abandon if taking too long - Be honest about limitations and blockers