169 lines
7.7 KiB
Markdown
169 lines
7.7 KiB
Markdown
---
|
|
created: 2026-08-03 15:43
|
|
modified: 2026-08-03 15:45
|
|
type: note
|
|
tags:
|
|
- ai
|
|
- planning
|
|
- flow-control
|
|
- architecture
|
|
aliases: []
|
|
---
|
|
# [[Ai planning flow control tools]]
|
|
|
|
## WhereWoof Implementation Pipeline
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ WHERE WOOF IMPLEMENTATION PIPELINE │
|
|
│ │
|
|
│ ┌──────────┐ ┌─────────────┐ ┌────────────┐ │
|
|
│ │ OpenSpec │────▶│ Plannotator │────▶│ Archon │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ "What │ │ "Let me │ │ "I'll │ │
|
|
│ │ to │ │ think │ │ run the │ │
|
|
│ │ build" │ │ first" │ │ agents" │ │
|
|
│ └────┬─────┘ └──────┬──────┘ └─────┬──────┘ │
|
|
│ │ │ │ │
|
|
│ proposal.md PLAN.md Workspaces │
|
|
│ specs/*.md (exploratory) Worktrees │
|
|
│ design.md Browser review Concurrent sessions │
|
|
│ tasks.md Approve/deny State persistence │
|
|
│ │ │ │ │
|
|
│ ▼ ▼ ▼ │
|
|
│ Formal artifacts Interactive gating Execution harness │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## OpenSpec — Spec-Driven Planning
|
|
|
|
**What:** CLI + pi extension (`@fission-ai/openspec` v1.3.1) for generating structured artifacts per change.
|
|
|
|
**Pipeline:** `proposal → specs → design → tasks`
|
|
|
|
| Artifact | Purpose |
|
|
|----------|---------|
|
|
| `proposal.md` | WHY — problem statement, scope |
|
|
| `specs/*.md` | WHAT — ADDED/MODIFIED/REMOVED requirements with testable scenarios |
|
|
| `design.md` | HOW — architecture decisions, risks, migration plan |
|
|
| `tasks.md` | Implementation checklist (`- [ ]` format) |
|
|
|
|
**Pi skills (4):**
|
|
|
|
| Skill | Trigger | Purpose |
|
|
|-------|---------|---------|
|
|
| `openspec-propose` | `/opsx:propose "name"` | Create a new change with all artifacts |
|
|
| `openspec-apply-change` | `/opsx:apply` | Implement tasks one-by-one, checking boxes |
|
|
| `openspec-explore` | `/opsx:explore` | Thinking partner — explores codebase, draws diagrams, never writes code |
|
|
| `openspec-archive-change` | `/opsx:archive` | Archive completed change |
|
|
|
|
**Current state:** Initialized at `~/chats/sys_config/openspec/` but empty — no active changes.
|
|
|
|
---
|
|
|
|
## Plannotator — Interactive Plan Review
|
|
|
|
**What:** pi extension (`@plannotator/pi-extension` v0.19.10) with browser-based plan approval UI. Toggle with `/plannotator` or Ctrl+Alt+P.
|
|
|
|
**Two gated phases:**
|
|
|
|
```
|
|
PLANNING PHASE EXECUTING PHASE
|
|
┌───────────────────┐ ┌──────────────┐
|
|
│ Tools: grep, find,│ approve │ Full tool │
|
|
│ ls, submit_plan │─────────────────▶│ access │
|
|
│ Writes: .md only │ │ │
|
|
│ No: code edits, │ │ [DONE:n] │
|
|
│ installs, commits │ │ markers │
|
|
└───────────────────┘ └──────────────┘
|
|
```
|
|
|
|
**Browser review:** Agent writes `PLAN.md` → `plannotator_submit_plan` opens browser UI → you review and approve/annotate.
|
|
|
|
**Storage:** `~/.plannotator/plans/`, history at `~/.plannotator/history/{project}/{slug}/`.
|
|
|
|
**Current state:** No WhereWoof plan exists yet. No `.pi/plannotator.json` project config.
|
|
|
|
---
|
|
|
|
## Archon — Persistent Execution Harness
|
|
|
|
**What:** Web-based orchestration layer on top of Pi. `ghcr.io/coleam00/archon:latest` v0.3.10. Runs on .27:3090 (Docker).
|
|
|
|
**Features:**
|
|
- Workspaces and Git worktrees for project isolation
|
|
- Concurrent agent sessions with queuing (max 10)
|
|
- State persistence via SQLite (`/.archon/archon.db`) — resume sessions after closing
|
|
- Multi-platform: Web, Telegram, Slack, Discord
|
|
- Uses Pi as its coding agent (`DEFAULT_AI_ASSISTANT=pi`)
|
|
|
|
**Current state:** Running and healthy, but empty workspaces — not yet configured for WhereWoof.
|
|
|
|
---
|
|
|
|
## The Three-Stage WhereWoof Flow
|
|
|
|
### Stage 1: OpenSpec initializes the formal spec
|
|
```bash
|
|
/opsx:propose "where-woof-website"
|
|
```
|
|
Generates all 4 artifacts:
|
|
- `proposal.md` — two-system architecture justification
|
|
- `specs/frontend-pet-tracker/spec.md` — QR scan, location, pet info display
|
|
- `specs/admin-dashboard/spec.md` — user/payment/device management
|
|
- `design.md` — Go net/http + HTMX + Laravel Filament
|
|
- `tasks.md` — 8 implementation phases as checkboxes
|
|
|
|
### Stage 2: Plannotator gates execution
|
|
Activate `/plannotator`. Pi can only read and plan during this phase. When `PLAN.md` is ready, browser review lets you annotate specific sections before approving full tool access.
|
|
|
|
### Stage 3: Archon manages long-running execution
|
|
Open `http://192.168.20.27:3090`, create a workspace pointing at the WhereWoof repo, and Archon:
|
|
- Kicks off `/opsx:apply` for task-by-task implementation
|
|
- Persists conversation state — resume anytime
|
|
- Queues concurrent agent sessions for parallel work (frontend + admin)
|
|
- Tracks task completion
|
|
|
|
---
|
|
|
|
## Goose & CrewAI — Evaluated
|
|
|
|
### Goose (Block / Linux Foundation)
|
|
|
|
| Aspect | Detail |
|
|
|--------|--------|
|
|
| **What** | Terminal-first AI agent in Rust. MCP-native. Apache 2.0. |
|
|
| **Vs pi** | Same coding agent slot. No sub-agent system. No persistent memory (upstream). Value is MCP extensibility + recipe-based automation. |
|
|
| **Verdict** | ❌ **Redundant.** Pi already fills the terminal coding agent role with sub-agent orchestration. Goose's MCP ecosystem is broader but doesn't fill a gap. |
|
|
|
|
### CrewAI
|
|
|
|
| Aspect | Detail |
|
|
|--------|--------|
|
|
| **What** | Python framework for role-based multi-agent orchestration. Define agents with roles (Researcher, Writer, Reviewer) and they collaborate. |
|
|
| **Vs existing** | Orthogonal. It's for building standalone multi-agent Python applications, not enhancing the coding loop. Overlaps with LangGraph. |
|
|
| **Verdict** | ❌ **Not worth adding.** No gap in the pi coding workflow. Consider if building a separate multi-agent research/review pipeline later. |
|
|
|
|
### What to use instead
|
|
|
|
| Your need | Right tool |
|
|
|-----------|-----------|
|
|
| Spec-driven planning | OpenSpec |
|
|
| Interactive plan review + gated execution | Plannotator |
|
|
| Long-running session persistence | Archon |
|
|
| Multi-agent Python applications (future) | LangGraph (planned later) |
|
|
| Simple role-based agent pipelines (future) | CrewAI (if LangGraph is too heavy) |
|
|
|
|
---
|
|
|
|
## Current Gaps for WhereWoof
|
|
|
|
| Gap | Action |
|
|
|-----|--------|
|
|
| No OpenSpec change | Run `openspec new change "where-woof-website"` |
|
|
| No Plannotator plan | Activate `/plannotator`, write PLAN.md |
|
|
| Archon workspaces empty | Create workspace → `http://192.168.20.27:3090` |
|
|
| No task tracking | Use Pi Dashboard `register_task` tool (project-local .pi/dashboard/tasks/todo.txt) |
|