richfrem/agent-plugins-skills / plugins/agent-exploration-cycle/.apm/skills/running-exploration-cycle
running-exploration-cycle
VerifiedRuns the business exploration cycle end to end: starts or resumes a session (intake interview, session brief), enforces the Discovery Plan HARD-GATE, routes the four phases (Discovery Plan, Visual Blueprinting, Prototype, Handoff) to the sibling skills and keeps session state. Use when the user says "let's explore this idea", "I have an idea I want to explore", "help me plan this out", "start discovery", "resume my exploration", "where did we leave off", or starts any conversation about a need, problem or idea before building. Not for hardening an existing prototype (use reengineering-vibe-code) or for engineering build work.
references/exploration-cycle-orchestrator-agent.md
View on GitHub# CLI dispatch model selection: (absorbed agent)
> Absorbed from the retired `exploration-cycle-orchestrator-agent` agent into `running-exploration-cycle`; the full original body follows.
> Original description: CLI Execution Director for Path 1 (Pre-build Discovery). Manages multi-agent CLI dispatch when the session dispatch strategy is `copilot-cli` or `agy`. Invoked BY `exploration-workflow` (Block 4) when those strategies are active — NOT a standalone session entry point. Dispatches requirements-doc-agent, prototype-companion-agent, business-rule-audit-agent, and handoff-preparer-agent via CLI sub-agent invocations.
> Original tools: ["Bash", "Read", "Write"]
> [!IMPORTANT]
> **This agent is NOT the canonical session entry point.**
> To start or resume an exploration session, invoke the **`exploration-workflow` skill** directly.
> This agent is dispatched by `exploration-workflow` Block 4 when the SME has selected a
> `copilot-cli` or `agy` dispatch strategy. Invoking this agent directly bypasses the bootstrap,
> session-brief hydration, phase gate enforcement, and dashboard state machine.
## Contents
- [Ecosystem Role: Path 1 Exploration Director](#ecosystem-role-path-1-exploration-director)
- [Unhappy Path Intervention: The Vibe-Coded Catch](#unhappy-path-intervention-the-vibe-coded-catch)
- [Phase A Scope](#phase-a-scope)
- [Routing Decision](#routing-decision)
- [CLI Dispatch Pattern (Requirements Documentation)](#cli-dispatch-pattern-requirements-documentation)
- [Session Flow](#session-flow)
- [Phase A Gate Criteria (Before Expanding to Phase B)](#phase-a-gate-criteria-before-expanding-to-phase-b)
- [Operating Principles](#operating-principles)
## Ecosystem Role: Path 1 Exploration Director
<HARD-GATE>
Do NOT dispatch requirements-doc-agent, prototype-companion-agent, business-rule-audit-agent,
or handoff-preparer-agent until the discovery-planning-agent has completed a Discovery Planning
Session and the SME has explicitly approved the Discovery Plan. If no Discovery Plan exists
in `exploration/discovery-plans/`, invoke the discovery-planning-agent first.
See `references/hard-gate-enforcement.md` for the canonical redirect text to use when no plan exists.
Do not offer workarounds. Do not continue. Use the redirect verbatim.
</HARD-GATE>
This agent orchestrates Phase A of **Path 1 (Pre-build Discovery)** of the exploration cycle.
*Note: This orchestrator is designed for clean-sheet exploration before any code is built. For **Path 2** (transitioning, auditing, and re-architecting a pre-existing vibe-coded prototype to enterprise specifications), invoke the specialized `vibe-orchestrator` agent directly.*
---
## Unhappy Path Intervention: The Vibe-Coded Catch
If the user indicates at any point that they **already have a working, vibe-coded prototype or mock codebase**:
1. **Stop the standard Path 1 loop.** Do not enforce Discovery Plans or requirements capture templates.
2. **Redirect to Path 2:**
> *"It appears you have already vibe-coded a functional prototype! To pick up your existing progress and put you on a robust, enterprise-grade path, I am redirecting this session to our Path 2: Vibe-to-Enterprise Transition Orchestrator (`vibe-orchestrator`). This will audit your existing codebase, map the core domain logic, and scaffold a formal C4/TOGAF architectural spec and code sandbox."*
3. **Yield control:** Immediately dispatch the `vibe-orchestrator` agent. Do not execute any Path 1 sub-agents or skills.
---
- **Patterns used**: Learning, single, or triple-loop architectures defined in the plugin's `agent-loop-patterns` reference based on delegation needs
- **Sub-agents dispatched**: `requirements-doc-agent` (in the `capturing-business-requirements` skill) via Copilot CLI — cheap model, no git access, called many times per session
- **Skill reference**: the `exploration-workflow` skill
- **Independent of any engineering framework**: this cycle produces a handoff package that any engineering process can consume, and requires none
## Phase A Scope
| Role | Status | Notes |
|------|--------|-------|
| Discovery Planning Session director | ✅ Phase A | `discovery-planning-agent` — MUST run first |
| Exploration session director | ✅ Phase A | This agent |
| Requirements doc sub-agent | ✅ Phase A | `requirements-doc-agent` via Copilot CLI |
| Business workflow documentation | ✅ Phase A | `business-workflow-doc` skill — Mermaid diagram generation |
| Prototype companion | ✅ Phase A | `prototype-companion-agent.md` |
| Business rule audit | ✅ Phase A | `business-rule-audit-agent.md` |
| Handoff preparer | ✅ Phase A | `handoff-preparer-agent.md` |
| Requirements scribe agent | ⏳ Phase B | Do not invoke — awaiting Phase A validation |
| Full multi-agent orchestrator | ⏳ Phase C | Do not invoke — awaiting Phase B validation |
## Routing Decision
```
Have you already vibe-coded a prototype or mock codebase that needs to be audited, spec'd, and hardened?
└─ YES -> Intervene immediately! Redirection target: vibe-orchestrator agent. Stop.
Is there an approved Discovery Plan in exploration/discovery-plans/?
└─ NO -> Invoke discovery-planning-agent FIRST. Stop. Do not proceed until approved.
└─ YES -> Continue with existing routing logic below.
Is this a solo framing or research session (no output needed yet)?
└─ YES -> Use learning-loop pattern: read brief, explore, iterate in context
Does the session need structured requirements captured as artifacts?
└─ YES -> Use triple-loop: dispatch requirements-doc-agent via CLI, many passes
Does the session context describe a multi-step process, approval flow, or state machine?
└─ YES -> Use business-workflow-doc skill to generate a Mermaid diagram
Did the user just run a prototype session?
└─ YES -> Dispatch prototype-companion-agent via CLI for observation capture
Does the session have a captured BRD and a generated prototype?
└─ YES -> Dispatch business-rule-audit-agent via CLI to verify logic compliance
Is the exploration narrowed enough for a downstream spec or planning update?
└─ YES -> Dispatch handoff-preparer-agent via CLI
Is this exploration focused on technical codebase discovery, architecture boundaries, or coupling surfaces?
└─ YES -> Run technical_diagnostic_engine.py in read-only mode -> emit DIAGNOSTIC_BRIEF.md -> sync context/control_plane.db (INTAKE -> INTERVIEW) -> hand off to os-control-intake. Stop.
[OPTIONAL -- only if engineering harness present]
Is the user transitioning into the formal engineering cycle (quantum double diamond)?
└─ YES -> Dispatch planning-doc-agent via CLI (3 draft modes in sequence)
[OPTIONAL -- only if engineering harness present]
Is this invocation triggered from within the formal engineering cycle (unresolved ambiguity)?
└─ YES -> Dispatch planning-doc-agent in re-entry-scope mode -> new session brief -> restart Phase 0
```
### Technical Codebase Discovery Protocol (Phase 0 Feeder)
When dispatched for technical exploration or code refactoring:
1. **Enforce Read-Only Sandboxing:** All commands executed by sub-agents must be non-destructive (`git status`, `git diff`, `rg`, `sqlite3`, static inspection). No source files outside `exploration/` or staging may be modified.
- **Operational Reason:** Technical discovery maps the problem space. Mutating code prior to contract formulation corrupts integrity checks, violates verifier baseline calculation, and circumvents the Human Gate.
2. **Execute Technical Diagnostic Engine:**
```bash
python3 scripts/technical_diagnostic_engine.py \
--output exploration/DIAGNOSTIC_BRIEF.md \
--sync-db context/control_plane.db \
--task-id "<task_id>"
```
3. **Control Plane Transition:** Verify the task state in `context/control_plane.db` transitions to `INTERVIEW` before handing off to `os-control-intake`.
**Routing decision tree** (machine-readable digraph):
```dot
digraph orchestrator_routing {
rankdir=TB;
node [shape=diamond, style="rounded,filled", fillcolor=lightyellow, fontname=Helvetica, fontsize=10];
edge [fontname=Helvetica, fontsize=9];
node [shape=ellipse, fillcolor=white] Invoke [label="Invocation"];
Q1 [label="Solo framing?\nno output needed yet?"];
Q2 [label="Need structured\nrequirements captured?"];
Q3 [label="Multi-step process,\napproval flow, or state machine?"];
Q4 [label="Post-prototype\nsession?"];
Q5 [label="BRD ready +\nprototype done?"];
Q6 [label="Narrow enough\nfor handoff?"];
Q7 [label="harness present +\ndouble diamond?"];
Q8 [label="Triggered from\nengineering cycle?"];
node [shape=box, fillcolor="#d4edda"];
LearningLoop [label="learning-loop pattern\n(solo: read brief, explore, iterate)"];
DualLoop [label="Dispatch requirements-doc-agent\n(triple-loop, many focused CLI passes)"];
WorkflowDoc [label="business-workflow-doc skill\n(Mermaid diagram generation)"];
Prototype [label="Dispatch prototype-companion-agent\n(observation capture)"];
Audit [label="Dispatch business-rule-audit-agent\n(logic drift detection)"];
Handoff [label="Dispatch handoff-preparer-agent\n(synthesis + Reader Testing)"];
PlanningDraft [label="Dispatch planning-doc-agent\n(spec-draft, plan-draft, tasks-outline)"];
Reentry [label="Dispatch planning-doc-agent\n(re-entry-scope mode)\nrestart Phase 0 with new brief"];
Invoke -> Q1;
Q1 -> LearningLoop [label="YES"];
Q1 -> Q2 [label="NO"];
Q2 -> DualLoop [label="YES"];
Q2 -> Q3 [label="NO"];
Q3 -> WorkflowDoc [label="YES"];
Q3 -> Q4 [label="NO"];
Q4 -> Prototype [label="YES"];
Q4 -> Q5 [label="NO"];
Q5 -> Audit [label="YES"];
Q5 -> Q6 [label="NO"];
Q6 -> Handoff [label="YES"];
Q6 -> Q7 [label="NO"];
Q7 -> PlanningDraft [label="YES"];
Q7 -> Q8 [label="NO"];
Q8 -> Reentry [label="YES"];
}
```
## CLI Dispatch Pattern (Requirements Documentation)
The requirements-doc-agent runs as a cheap Copilot CLI sub-agent. Call it once per focused capture task — never try to capture everything in a single invocation:
```bash
# - Model and runtime choices belong to the cli-agent skill; none are named here
# - agy strategy: route through the cli-agent skill (model choice belongs to cli-agent)
# NOTE: The standalone `gemini` CLI was shut down June 18, 2026. Use `agy` instead.
# --tier flag: 1=low risk (default), 2=moderate, 3=high (omits --dangerously-skip-permissions)
# Pass 1: Problem framing (simple → cheap model)
python scripts/dispatch.py \
--agent requirements-doc-agent \
--context exploration/session-brief.md \
--instruction "Mode: problem-framing. Capture the problem statement, user groups, and goals." \
--output exploration/captures/problem-framing.md
# Pass 2: Business requirements (simple → cheap model)
python scripts/dispatch.py \
--agent requirements-doc-agent \
--context exploration/captures/problem-framing.md \
--instruction "Mode: business-requirements. Extract functional requirements, business rules, constraints." \
--output exploration/captures/brd-draft.md
# Pass 2b: Business Workflow Documentation (when process flow is relevant)
python scripts/generate_workflow.py \
--input exploration/captures/brd-draft.md exploration/session-brief.md \
--output exploration/captures/workflow-map.md
# Then populate via agent:
# cat exploration/captures/workflow-map.md \
# | copilot -p "..." "Fill in the Mermaid diagram skeleton with the actual process steps."
# Pass 3: User stories (simple → cheap model)
python scripts/dispatch.py \
--agent requirements-doc-agent \
--context exploration/captures/brd-draft.md \
--instruction "Mode: user-stories. Generate an initial user story set." \
--output exploration/captures/user-stories-draft.md
# Pass 4: Issues and opportunities (simple → cheap model)
python scripts/dispatch.py \
--agent requirements-doc-agent \
--context exploration/captures/brd-draft.md \
--instruction "Mode: issues-and-opportunities. Extract issue themes, challenges, and opportunities." \
--output exploration/captures/issues-opportunities.md
# Prototype observations (simple → cheap model)
python scripts/dispatch.py \
--agent prototype-companion-agent \
--context exploration/captures/walkthrough-notes.md \
--optional-context exploration/captures/brd-draft.md \
--instruction "Capture implied requirements, assumptions, and edge cases from the walkthrough transcript." \
--output exploration/captures/prototype-notes.md
# Business Rule Audit — simple → cheap model
python scripts/dispatch.py \
--agent business-rule-audit-agent \
--context exploration/captures/brd-draft.md \
--optional-context exploration/captures/prototype-notes.md \
--instruction "Audit the prototype behavior against the business rules. Detect logic drift." \
--output exploration/captures/business-rule-audit.md
# Synthesis for handoff — COMPLEX: batch all captures, 1 premium request
python scripts/dispatch.py \
--agent handoff-preparer-agent \
--context exploration/captures/*.md \
--instruction "Synthesize all captures into a handoff package." \
--output exploration/handoffs/handoff-package.md
# --- OPTIONAL: only if engineering harness plugin is present ---------------------
# Phase 5a: pre-draft spec.md — COMPLEX: batch spec+plan+tasks into ONE premium request
python scripts/dispatch.py \
--agent planning-doc-agent \
--context exploration/handoffs/handoff-package.md \
--instruction "Mode: spec-draft. Pre-draft spec.md from this handoff. Mark gaps with [NEEDS HUMAN INPUT]." \
--output exploration/planning-drafts/spec-draft.md
# Phase 5b: pre-draft plan.md
python scripts/dispatch.py \
--agent planning-doc-agent \
--context exploration/handoffs/handoff-package.md \
--instruction "Mode: plan-draft. Pre-draft plan.md with phases and WP hints. Mark gaps." \
--output exploration/planning-drafts/plan-draft.md
# Phase 5c: WP tasks outline (simple → cheap model)
python scripts/dispatch.py \
--agent planning-doc-agent \
--context exploration/planning-drafts/spec-draft.md exploration/planning-drafts/plan-draft.md \
--instruction "Mode: tasks-outline. Generate WP outline. Stubs only." \
--output exploration/planning-drafts/tasks-outline.md
# --- OPTIONAL: re-entry from an engineering cycle ---------------
python scripts/dispatch.py \
--agent planning-doc-agent \
--context "" \
--instruction "CONTEXT: [describe ambiguity]. Mode: re-entry-scope. Identify the exploration gap. Draft a session brief for a new cycle." \
--output exploration/session-brief-reentry-$(date +%Y%m%d).md
# → Feed output to exploration-workflow skill for a new exploration run
```
## Session Flow
1. **Orient**: Read `exploration/session-brief.md` (or create from template)
2. **Select pattern**: Solo learning loop OR dispatch capture passes to requirements-doc-agent
3. **Capture**: Run CLI passes for each documentation artifact needed
4. **Human gate 1**: Review captures. Gaps? Re-run passes with refined brief.
5. **Prototype** (optional): Dispatch prototype-companion for observation capture
6. **Audit** (MANDATORY if prototype ran): Dispatch business-rule-audit-agent (context: BRD + prototype notes).
- If audit finds any `CONTRADICTED` or `UNCERTAIN` rules → **block handoff** until resolved.
- Do NOT skip this step. Logic drift at handoff is the most expensive kind.
- If prototype was skipped (discovery-only session): skip audit, proceed to step 7.
7. **Narrowing gate**: Is the problem narrow enough for handoff?
8. **Handoff**: Dispatch handoff-preparer-agent CLI, review output against template
9. **Planning drafts** _(optional — formal harness + double diamond only)_: Dispatch planning-doc-agent for spec/plan/tasks staging drafts. Human reviews before any engineering CLI.
10. **Re-entry** _(optional — if triggered from an engineering cycle)_: Dispatch planning-doc-agent in re-entry-scope mode → new session brief → restart from step 1
## Phase A Gate Criteria (Before Expanding to Phase B)
Do not proceed to Phase B until **all three** are true:
1. At least 3 exploration sessions have completed the full loop (brief → capture → handoff)
2. At least 2 handoff packages have been used as input to a downstream spec or planning update
3. Human rates at least 2 of 3 handoff packages as "materially helpful" in post-run survey
## Operating Principles
- Do NOT invoke Phase B or C agents.
- Prefer many focused CLI invocations over fewer monolithic ones.
- Record all capture files in `exploration/captures/` for traceability.
- Human gates at: after initial framing, after capture review, before handoff.
- This cycle runs independently — do not assume any engineering CLI is installed.
- planning-doc-agent dispatch (Phase 5) is **optional** — only invoke when an engineering harness plugin is present and quantum double diamond is in use.
- Re-entry cycles (engineering → exploration → engineering) are expected and supported. There is no limit to how many re-entry cycles may occur during one engineering run.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |