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/architecture.md
View on GitHub# Exploration Cycle Plugin Architecture Reference
## Contents
- [Intent](#intent)
- [Phase A Implementation (Current)](#phase-a-implementation-current)
- [Next Capability Groups (Phase B+)](#next-capability-groups-phase-b)
- [Evaluation Expectations](#evaluation-expectations)
- [Canonical Artifact Conventions](#canonical-artifact-conventions)
## Contents
- [Intent](#intent)
- [Phase A Implementation](#phase-a-implementation-current)
- [Next Capability Groups](#next-capability-groups-phase-b)
- [Evaluation Expectations](#evaluation-expectations)
- [Canonical Artifact Conventions](#canonical-artifact-conventions)
This plugin is the implementation boundary for the exploration-cycle system. The architecture and spec documents are maintained within this plugin's `references/` directory.
## Intent
The plugin provides:
- an orchestrated multi-agent exploration loop
- skill-level generation of core exploration artifacts
- prototype generation support
- handoff generation into formal spec workflows
- optimization loops for improving the exploration process itself
It is intentionally not designed around a specific MCP architecture, model vendor, or IDE shell. The plugin acts as a repository-native workflow package feeding whichever engineering process the receiving team uses (see `handing-off-to-engineering`).
Implementation is incremental. The repository validates the smallest useful exploration loop before hardening this plugin boundary into a richer workflow package.
---
## Phase A Implementation (Current)
### Agents
| Agent | Role | Status |
|-------|------|--------|
| `intake-agent` | Front-door interviewer — clarifies session type, pre-fills session brief | ✅ Phase A |
| `exploration-cycle-orchestrator-agent` | Coordinates the full Phase A loop | ✅ Phase A |
| `requirements-doc-agent` | Cheap CLI sub-agent — 5 capture modes | ✅ Phase A |
| `problem-framing-agent` | Optional higher-touch interactive framing alternative | ✅ Phase A |
| `prototype-companion-agent` | Cheap CLI sub-agent — prototype observation capture | ✅ Phase A |
| `handoff-preparer-agent` | Cheap CLI sub-agent — synthesizes captures into handoff | ✅ Phase A |
| `planning-doc-agent` | Optional — pre-drafts planning artifacts; re-entry scope mode | ✅ Phase A |
### Skills
| Skill | Purpose | Status |
|-------|---------|--------|
| `exploration-workflow` | SME-facing state machine orchestrator. Manages `exploration-dashboard.md`, enforces 4-phase gates, routes to child skills. Single canonical entry point. | ✅ Phase A |
| `exploration-session-brief` | Session brief creation and refinement | ✅ Phase A |
| `business-requirements-capture` | BRD generator — `brd / rules / constraints` modes | ✅ Phase A |
| `user-story-capture` | Story generator — `standard / gherkin` AC formats | ✅ Phase A |
| `business-workflow-doc` | Mermaid diagram generator — `flowchart / stateDiagram / sequenceDiagram` | ✅ Phase A |
| `prototype-builder` | Exploratory prototype generation | ✅ Phase A |
| `exploration-handoff` | Handoff synthesis | ✅ Phase A |
| `discovery-planning` | HARD-GATE discovery sessions for SME alignment | ✅ Phase A |
| `visual-companion` | Layout discovery and flowchart mocking | ✅ Phase A |
| `subagent-driven-prototyping` | Focused component-by-component prototype assembly | ✅ Phase A |
### Phase A Capture Output Classes
All of these are now available in Phase A:
1. Living discovery document / session brief
2. Business requirements document (functional, non-functional, rules, constraints)
3. Business workflow diagrams (Mermaid: flowchart, state machine, sequence)
4. User stories — standard format + Gherkin Acceptance Criteria
5. Issues, challenges, and opportunities capture
6. Prototype evidence and observations
7. Exploration handoff package
---
## Next Capability Groups (Phase B+)
1. **Phase B**: Background requirements scribe — autonomous passive capture during sessions
2. **Phase C**: Full multi-agent orchestrator with telemetry and routing rules
3. **Phase D**: Goals & objectives capture, roadmap routing, advanced story specialization
---
## Evaluation Expectations
The exploration-cycle plugin is designed from the start for repeated-run evaluation.
Early runs capture manual friction notes and outcome summaries to establish a baseline before adding optimization machinery.
The orchestrator is expected to emit or maintain:
- loop-state telemetry
- routing and agent-invocation traces
- handoff and re-entry decisions
- run-level artifact outcomes
- a post-run orchestrator survey
The `os-lab-*` skills in `agent-agentic-os` use those outputs in a baseline-first, one-hypothesis-at-a-time improvement loop (the former `exploration-optimizer`, kept as [exploration-optimizer.md](exploration-optimizer.md)).
---
## Canonical Artifact Conventions
### The `[NEEDS HUMAN INPUT]` Marker
Every agent and skill in this plugin that generates artifacts uses the following canonical marker for unresolved gaps:
```
[NEEDS HUMAN INPUT]
```
**Format rules (case- and format-sensitive):**
- All uppercase, exactly as written above
- Square brackets, no italics, no variation
- `check_gaps.py` counts this exact string — any variation (lowercase, em-brackets, italic `*[NEEDS HUMAN INPUT]*`) will be silently missed by the gap checker
**When to use it:**
- A required field cannot be filled from existing captures
- An assumption has not been explicitly confirmed by the SME
- A question was raised but not answered during exploration
**Consolidation rule:** Do not scatter this marker without consolidation. Every agent that uses this marker must also maintain a `## Consolidated Gaps` section (or equivalent "Remaining Unknowns") that lists each distinct unresolved decision once. Reference the consolidated entry in other sections rather than repeating the marker.
**Agents that use this marker:** `handoff-preparer-agent`, `requirements-doc-agent`, `planning-doc-agent`, `user-story-capture` skill. When adding a new agent or skill that produces artifacts, link to this section and follow these conventions.
### The `[CONFIRMED]` / `[UNCONFIRMED]` Status Tags
Use these alongside source citations on major claims:
- `[CONFIRMED]` — explicitly validated by the SME during the session
- `[UNCONFIRMED]` — derived from captures but not explicitly approved
Never promote `[UNCONFIRMED]` to `[CONFIRMED]` without explicit SME sign-off in the session.
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: 471k | 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 |