--- 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) |