docs: two POC modes — branch vs standalone scratch project
- pocs.md: define both modes + per-POC assignment (POC-1/2 standalone at /workspace/alkgit-pocN, POC-3 branch mode); findings are the deliverable, POC source never merges to main - sdd_process.md: phase 0 + POC Specialist sections cover both modes - poc-specialist.md: mode determination up front, standalone environment section, 'stay in your lane' principle updated - AGENTS.md: lifecycle status describes the two modes Verified: none needed (markdown only)
This commit is contained in:
1 parent
4d3ec3cc63
commit
b9ab5e4c9e
4 files changed
+88
-15
No files matched your search
+29
-4
@@ -1,8 +1,24 @@
|
||||
# alkgit POC Plan
|
||||
|
||||
POCs live in research worktrees (`.worktrees/research/<task-id>/`) 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/<poc-name>` (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.
|
||||
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.
|
||||
+22
-6
@@ -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/<poc-name>`, 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/<task-id>/` → Implementation Specialist
|
||||
- Research POCs: `.worktrees/research/<task-id>/` → POC Specialist
|
||||
- Research POCs building on repo code: `.worktrees/research/<task-id>/`
|
||||
→ POC Specialist (branch mode)
|
||||
- Research POCs independent of repo code: standalone scratch project at
|
||||
`/workspace/<poc-name>` → 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/<task-id>/`
|
||||
**Worktree Location**: `.worktrees/research/<task-id>/` (branch mode) or
|
||||
`/workspace/<poc-name>` (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
|
||||
|
||||
|
||||
Reference in new issue
Block a user