Skip to content

richfrem/agent-plugins-skills / plugins/agent-exploration-cycle/.apm/skills/running-exploration-cycle

running-exploration-cycle

Verified

Runs 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.

FileKindSize
SKILL.mdskill md4.6 KB
assets/exploration-dashboard.mdmarkdown1.8 KB
evals/evals.jsonconfig6.0 KB
references/acceptance-criteria.mdmarkdown2.2 KB
references/architecture.mdmarkdown6.3 KB
references/design-rationale.mdmarkdown6.3 KB
references/discovery-planning-agent.mdmarkdown4.7 KB
references/discovery-planning-tracks.mdmarkdown5.9 KB
references/discovery-planning.mdmarkdown2.4 KB
references/dispatch-strategies.mdmarkdown5.7 KB
references/domain-patterns-exploration-session.mdmarkdown3.3 KB
references/domain-patterns.mdmarkdown1.7 KB
references/environment-check.mdmarkdown1.7 KB
references/exploration-cycle-orchestrator-agent.mdmarkdown16.7 KB
references/exploration-optimizer.mdmarkdown8.9 KB
references/exploration-orchestrator-guide.mdmarkdown3.7 KB
references/exploration-session-brief.mdmarkdown2.1 KB
references/exploration-workflow.mdmarkdown2.4 KB
references/hard-gate-enforcement.mdmarkdown3.3 KB
references/high-level-process.mmdother885 B
references/intake-agent.mdmarkdown12.0 KB
references/orchestrator-loop.mmdother1.3 KB
references/post-run-survey.mdmarkdown1.7 KB
references/problem-framing-agent.mdmarkdown2.7 KB
references/process-definition.mdmarkdown3.7 KB
references/process-overview.mmdother3.7 KB
references/session-setup.mmdother1.3 KB
references/state-and-gates.mmdother1.0 KB
references/using-exploration-cycle.mdmarkdown2.3 KB
requirements-dev.inother69 B
requirements.inother60 B
scripts/check_gaps.pyscript2.5 KB
scripts/dispatch.pyexecutablescript23.6 KB
scripts/exploration_session.pyexecutablescript15.9 KB
scripts/sandbox_runner.pyscript8.7 KB
scripts/smoke_test.pyscript5.1 KB
scripts/state_engine.pyscript21.9 KB
scripts/test_dispatch_authorization_gate.pyscript4.0 KB
scripts/test_dispatch_security.pyscript10.0 KB
scripts/test_exploration_integration.pyscript14.7 KB
scripts/test_integration.pyscript4.4 KB
scripts/test_path_traversal.pyscript1.8 KB
scripts/test_phase_premium_counter.pyscript2.0 KB
scripts/test_sandbox_runner.pyscript5.6 KB
scripts/test_session_start_hook.pyscript2.4 KB
scripts/test_state_engine.pyscript13.5 KB
scripts/test_validate_phase_gate.pyscript12.7 KB
scripts/validate_phase_gate.pyexecutablescript8.7 KB

scripts/test_integration.py

View on GitHub
"""
Purpose:
    Integration tests for the agent-exploration-cycle control plane spanning
    state_engine.py, sandbox_runner.py, and dispatch.py together: concurrent
    task-completion races, sandbox environment leak prevention, and approval
    expiry rejection.

Key Input Dependencies:
    - state_engine.py, sandbox_runner.py, dispatch.py modules (in ../scripts/)
    - pytest tmp_path and monkeypatch fixtures
"""
import sys, uuid, time, threading
from pathlib import Path
import pytest

sys.path.insert(0, str(Path(__file__).parent))
import state_engine as SE
import sandbox_runner as SR


@pytest.fixture
def db_conn(tmp_path):
    """Yield a fresh file-backed SQLite connection, closed on teardown."""
    conn = SE.init_db(str(tmp_path / "test.sqlite"))
    yield conn
    conn.close()


def _seed_leased_tasks(conn, count: int = 5) -> tuple:
    """Insert `count` tasks directly as 'leased', bypassing MAX_PARALLEL_AGENTS.

    Exercises concurrent commit_task_complete calls, not the lease gate itself.
    Returns (task_ids, versions) for the caller to use in completion threads.
    """
    task_ids = [str(uuid.uuid4()) for _ in range(count)]
    for i, tid in enumerate(task_ids):
        conn.execute(
            "INSERT INTO tasks (id, session_id, phase_ordinal, phase_name, component_name, "
            "status, assigned_subagent_id, lease_expires_at, version) "
            "VALUES (?, 'sess-c', ?, ?, ?, 'leased', ?, datetime('now', '+300 seconds'), 1)",
            (tid, i + 1, f"Phase {i + 1}", f"Comp {i}", f"subagent-{i}"),
        )
    conn.execute(
        "UPDATE sessions SET parallel_agents_running = ? WHERE id = 'sess-c'", (count,)
    )
    conn.commit()

    versions = {}
    for tid in task_ids:
        row = conn.execute("SELECT version FROM tasks WHERE id=?", (tid,)).fetchone()
        versions[tid] = row["version"]
    return task_ids, versions


def test_concurrent_task_completions(tmp_path):
    """5 concurrent threads completing distinct tasks must all succeed within 30s."""
    db_path = tmp_path / "concurrent.sqlite"
    conn = SE.init_db(str(db_path))
    SE.create_session(conn, "sess-c", "Concurrent Session")

    task_ids, versions = _seed_leased_tasks(conn)

    results, errors = [], []

    def complete_task(tid, agent_id, version):
        """Complete one task on its own thread-local DB connection, recording result or error."""
        try:
            thread_conn = SE.init_db(str(db_path))
            ok = SE.commit_task_complete(thread_conn, tid, agent_id, version, f"hash-{tid[:8]}")
            results.append(ok)
            thread_conn.close()
        except Exception as e:
            errors.append(str(e))

    threads = [
        threading.Thread(target=complete_task, args=(tid, f"subagent-{i}", versions[tid]))
        for i, tid in enumerate(task_ids)
    ]
    start = time.time()
    for t in threads:
        t.start()
    for t in threads:
        t.join(timeout=30)
    elapsed = time.time() - start

    assert not errors, f"Threads raised: {errors}"
    assert elapsed < 30
    assert sum(results) == 5
    final = conn.execute("SELECT COUNT(*) FROM tasks WHERE status='complete'").fetchone()[0]
    assert final == 5
    conn.close()


def test_sandbox_env_vars_do_not_leak(monkeypatch):
    """ANTHROPIC_API_KEY and PYTHONPATH must not be visible inside sandboxed process."""
    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-secret")
    monkeypatch.setenv("PYTHONPATH", "/injected")
    result = SR.run_hygienic(
        [sys.executable, "-c",
         "import os, sys; "
         "leaked = [k for k in ['ANTHROPIC_API_KEY', 'PYTHONPATH'] if k in os.environ]; "
         "sys.exit(len(leaked))"],
        timeout=10,
    )
    assert result.returncode == 0


def test_expired_approval_is_rejected(db_conn):
    """Verify check_approval rejects an approval whose expires_at is in the past."""
    import dispatch
    approval_id = str(uuid.uuid4())
    SE.create_session(db_conn, "sess", "Expiry Session")
    db_conn.execute("""
        INSERT INTO approvals (id, session_id, phase, approved_actions, allowed_paths,
            spec_hash, spec_source_path, is_active, expires_at)
        VALUES (?, 'sess', 'p1', '[]', '[]', 'abc', '/spec.md', 1,
                datetime('now', '-1 second'))
    """, (approval_id,))
    db_conn.commit()
    is_valid, reason = dispatch.check_approval(db_conn, approval_id)
    assert is_valid is False
    assert "expired" in reason.lower()
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall