skillweave-promptchain-execute

name	skillweave-promptchain-execute
type	orchestration
description	Execute SkillWeave prompt sequences with dependency-aware batching, Ralph Loop execution, binary gates, and safe parallel subagent orchestration. Orchestration substrate — does NOT handle release-specific logic (see skillweave-releasechain for release).
argument-hint	sequence="[prompt sequence]" inputs="[JSON]" execution_mode="[auto/rex/ralph_attended/ralph_overnight]" audience_mode="[auto/humanize/machinize/mixed]" risk_mode="[conservative/medium/unicorn]" (or attach .md/.txt file)

/skillweave-promptchain-execute

Execute structured prompt sequences with real delivery discipline.

This skill is the execution engine for SkillWeave prompt sequences. It does not just "run steps"; it resolves execution mode, plans batches, identifies safe parallel lanes, applies Ralph Loop when the work is substantial, and advances only through binary gates.

Mandatory Pre-Flight: SkillWeave Sandboxing

Before generating any output, you MUST verify and enforce the SkillWeave sandbox. This applies to every skill invocation without exception:

1. Enforce .skillweave/ Directory Structure

If .skillweave/ does not exist in the project root, create it:

.skillweave/
.skillweave/tracking-log/
.skillweave/templates/
.skillweave/sequences/

2. Route All Outputs Into .skillweave/

All execution sequences, batch plans, gate logs, and state trackers MUST be saved exclusively within .skillweave/ or its sub-folders. Never dump artifacts into the repository root.

3. Git Isolation

Check .gitignore — if .skillweave/ is not listed, append it. AI-generated execution files are excluded from source control.

4. Default Config

If .skillweave/config.yaml does not exist, create it with:

mode: medium
checklist: true
design_thinking: true
community_knowhow: true
modular_templates: true

Proceed with core skill logic only AFTER these four criteria are met.

Usage

/skillweave-promptchain-execute sequence="[prompt sequence text]" inputs="[JSON inputs]"

Or attach a .md / .txt sequence file and provide:

/skillweave-promptchain-execute inputs='{"key":"value"}'

Parameters

• sequence (optional if file attached): Prompt sequence text
• inputs (required): JSON object with required runtime inputs
• execution_mode (optional): auto, rex, ralph_attended, ralph_overnight
• audience_mode (optional): auto, humanize, machinize, mixed
• risk_mode (optional): conservative, medium, unicorn - overrides environment variable and config files

Default:

• execution_mode = auto
• audience_mode = auto
• risk_mode = medium (unless overridden by environment variable or config)

Core Distinctions

1. Sequence Type

Sequence type describes the nature of the work:

• plan: strategy, analysis, PRD, architecture, research-led planning
• build: code, config, tests, infra, docs tied to implementation
• mixed: both plan and build steps are materially present

2. Execution Mode

Execution mode describes how the work should be carried out:

• rex: fast path for small, low-risk, mostly linear work
• ralph_attended: default for substantial repo work with active checkpoints
• ralph_overnight: autonomous multi-batch execution for large, well-structured sequences

mixed is not an execution mode. It is only a sequence-type classification.

Mode Resolution

If execution_mode=auto, choose as follows:

Use rex when:

• there are 1-3 steps
• total work is small
• dependencies are mostly linear
• there is no meaningful public/private or release boundary risk
• verification is lightweight

Use ralph_attended when:

• there are 4+ steps
• the work mutates a repository
• code, tests, or docs are all involved
• binary gates are required
• public/private or product-tier boundaries are involved
• multiple safe parallel lanes exist

Use ralph_overnight when:

• the sequence is already decomposed into explicit batches
• batch gates are well-defined
• retries and carry-forward logic are already specified
• long autonomous execution is acceptable

Rule of thumb:

• default to ralph_attended for real product development unless the task is obviously tiny

Next Level Features

SkillWeave Next Level provides advanced capabilities that can enhance prompt chain execution. These features are controlled by .skillweave/config.yaml and can be accessed via the SkillWeaveNextLevel class.

Risk Mode Integration

SkillWeave v0.5.5 introduces a hierarchical override system for risk mode. The effective risk mode is determined by the following precedence order (highest to lowest):

1. CLI parameter: risk_mode="conservative/medium/unicorn" (if provided)
2. Environment variable: SKILLWEAVE_RISK_MODE (if set)
3. Project config: .skillweave/config.yaml mode setting
4. Global config: ~/.skillweave/config.yaml mode setting
5. Default: medium

Use the RiskModeResolver class from skillweave.risk_mode_resolver to resolve the effective risk mode programmatically.

Command-line utilities:

• skillweave-risk-mode - shows effective risk mode given current context. Use skillweave-risk-mode --cli-risk-mode=conservative --verbose to see precedence resolution.
• skillweave-interactive-mode - interactive risk mode selection with project analysis and persistence options (temporary, project config, global config).

Adjust execution behavior according to the effective risk mode:

• Conservative: Extra validation, explicit approvals, strict safety checks
• Medium: Balanced approach with standard validation
• Unicorn: Optimistic assumptions, minimal confirmations, maximum speed

Checklist-Based Execution

If checklist: true is set in the config, the skill will:

• Parse markdown checklists (- [ ] and - [x]) from sequence inputs
• Track checklist item completion across batches using .skillweave/tracking-log/
• Loop until all checklist items are marked complete
• Provide progress reports and remaining items

Design-Thinking Lens

If design_thinking: true is set in the config, apply these cognitive ergonomics principles to outputs:

1. Value ≥ Noise: Ensure every execution output provides clear user value
2. Scan Before Read: Structure batch reports for quick scanning with clear headings
3. Hierarchy of Needs: Address functional needs before advanced features
4. Progressive Disclosure: Reveal complexity gradually as needed
5. Recognition Over Recall: Use consistent patterns and familiar formats
6. Error Tolerance: Design for mistakes with clear recovery paths

Community Know-How

If community_knowhow: true is set, the skill will:

• Extract patterns from .skillweave/tracking-log/ across projects
• Provide repository cleanup recommendations based on common issues
• Suggest optimizations and best practices from community patterns

Modular Templates

If modular_templates: true is set, the skill can:

• Load and combine templates from .skillweave/templates/ for batch planning
• Use template inheritance for consistent execution reports
• Generate custom sequence sections from reusable components

Using Next Level Features

from skillweave.next_level import SkillWeaveNextLevel

# Initialize with project root
next_level = SkillWeaveNextLevel("/path/to/project")

# Check feature availability
if next_level.is_checklist_enabled():
    checklist = next_level.parse_checklist(markdown_content)
    # Track progress, loop until completion

if next_level.is_design_thinking_enabled():
    lens = next_level.get_design_thinking_lens()
    lens.apply_to_output(your_content)

# Access other features similarly

Adjust your execution based on enabled features to provide enhanced results while maintaining backward compatibility.

Intelligent Guidance (v0.5.5)

SkillWeave v0.5.5 introduces intelligent prompt analysis and onboarding flows that help ensure you're using the right skill with the right parameters.

How It Works

When this skill is invoked, you should first use the SkillIntegrationHelper to analyze the user's prompt and validate the request:

from skillweave.intelligent_detection import integrate_with_skill
import os

# Determine project root (current directory or parent containing .skillweave/)
project_root = os.getcwd()
if not os.path.exists(os.path.join(project_root, ".skillweave")):
    # Try parent directory
    parent = os.path.dirname(project_root)
    if os.path.exists(os.path.join(parent, ".skillweave")):
        project_root = parent

result = integrate_with_skill(
    user_prompt=user_prompt,  # The original user prompt
    current_skill="skillweave-promptchain-execute",  # This skill's name
    project_root=project_root
)

Handling the Result

The integrate_with_skill function returns a dictionary with an action key:

1. action: "proceed" - Skill selection is appropriate, parameters are valid

   • Continue with normal skill execution
   • Use result["validated_parameters"] for parameter values
   • Apply result["mode_override"] if present (risk mode from CLI/env)

2. action: "gather_parameters" - Missing or invalid parameters detected

   • Show result["missing_parameters"] to the user
   • Ask for each missing parameter using result["parameter_prompts"]
   • Use interactive Q&A to gather all required information
   • After gathering, re-run integrate_with_skill with updated parameters

3. action: "switch_skill" - Different skill might be more appropriate

   • Consider switching to result["recommended_skill"]
   • Show explanation: result["switch_reason"]
   • Ask user for confirmation before switching
   • If confirmed, load the recommended skill instead

4. action: "onboarding_flow" - User needs guided onboarding

   • Follow the interactive onboarding flow
   • Use result["onboarding_steps"] for guidance
   • Gather information step by step
   • Complete onboarding before skill execution

Benefits

• Skill Validation: Ensures this skill is appropriate for the task
• Parameter Completeness: Checks all required parameters are provided
• Intelligent Routing: Suggests better-suited skills when applicable
• Guided Onboarding: Helps new users through step-by-step setup
• Learning System: Improves recommendations based on user feedback

Integration with Existing Features

The intelligent guidance system works alongside existing Next Level features:

• Respects risk mode overrides from CLI, environment, or config
• Uses the same project root and configuration
• Integrates with checklist tracking and design thinking
• Maintains backward compatibility

Example Workflow

# 1. Analyze user prompt
result = integrate_with_skill(user_prompt, "skillweave-blueprint", project_root)

# 2. Handle result
if result["action"] == "proceed":
    # Extract validated parameters
    params = result["validated_parameters"]
    # Apply risk mode override if present
    if "mode_override" in result:
        set_risk_mode(result["mode_override"])
    # Execute skill with validated parameters
    execute_skill(params)
    
elif result["action"] == "gather_parameters":
    # Interactive parameter gathering
    for param in result["missing_parameters"]:
        prompt = result["parameter_prompts"].get(param, f"Enter value for {param}:")
        value = ask_user(prompt)
        # Update parameters and re-validate
        # (In practice, you'd collect all then re-validate)
        
elif result["action"] == "switch_skill":
    # Suggest skill switch
    if confirm_switch(result["recommended_skill"], result["switch_reason"]):
        load_skill(result["recommended_skill"])

Always use intelligent guidance when executing this skill to provide the best user experience and ensure successful outcomes.

Git Flow Convention

When executing build or mixed sequences in a git repository, SkillWeave enforces a minimum branching discipline. This prevents work from landing directly on protected branches and ensures a reviewable integration path.

Branch Model

Branch	Purpose	Protected
main	Release-ready, tagged with vX.Y.Z	Yes — no direct commits
dev	Integration branch, CI must be green	Yes — only via PR
feature/<id>-<slug>	New functionality, branched from dev	No
fix/<id>-<slug>	Bug fixes, branched from dev	No
chore/<slug>	Maintenance, docs, CI changes	No

Preflight Detection (before any build work)

Before creating a branch or committing, check the repository state:

1. Does dev exist? If not, recommend creating it from main and explain why.
2. Is the current branch main? Warn the user and recommend branching to dev or a feature branch. Never commit build work directly to main.
3. Is there an existing branch for this task? Search for open branches matching the task ID or slug. If found, offer to continue on that branch instead of creating a new one.
4. Is dev up to date with main? If dev is behind main, recommend rebasing or merging main into dev before branching.

If the user explicitly opts out (e.g., single-branch workflow), respect their choice but log the decision in .skillweave/tracking-log/.

Branch Creation

When starting build work:

1. Determine branch type from the task/PRD context:
   • PRD tasks with new features → feature/<ticket-id>-<slug>
   • Bug fixes or patches → fix/<ticket-id>-<slug>
   • Maintenance, docs, CI → chore/<slug>
2. Branch from dev (not from main)
3. Log the branch name in .skillweave/tracking-log/ for continuity across sessions

Merge Flow

The expected merge path for build work:

feature/FEAT-001-auth  →  PR to dev  →  PR to main  →  tag vX.Y.Z

• Feature branch → dev: Created by promptchain-execute or releasechain after build gates pass. Requires tests green.
• dev → main: Created by releasechain as the release PR. Requires all integration tests green, changelog updated, version bumped.
• Tag on main: Created by releasechain or launch after merge to main.

Configuration

The git flow can be configured in .skillweave/config.yaml:

git_flow:
  enabled: true
  branches:
    production: main
    integration: dev
  branch_prefix:
    feature: feature/
    fix: fix/
    chore: chore/
  require_pr: true
  auto_create_dev: false

If git_flow.enabled is false or missing, skip branch enforcement but still warn when committing directly to main.

Execution Process

Phase 1: Preflight

1. Detect sequence type: plan, build, or mixed
2. Validate required inputs
3. Parse dependencies
4. Identify:
   • critical path
   • safe parallel lanes
   • review gates
   • handoff boundary to releasechain/launch (see .skillweave/release/skill-boundaries.yaml)
5. Resolve execution mode
6. Resolve effective risk mode using hierarchical override system (CLI parameter > environment variable > project config > global config > default)
7. Evaluate git flow state (see Git Flow Convention above):
   • Detect branch model (dev exists? current branch? open feature branches?)
   • Create or switch to appropriate work branch
   • Warn if working directly on main or dev
8. Determine whether the sequence should run:
   • as one batch
   • as multiple batches
   • with sidecar subagents

If the sequence is malformed, underspecified, or contradicts the real repository baseline, stop and produce a baseline-alignment report before executing.

Phase 2: Batch Planning

Before implementation, convert the sequence into executable batches.

For each batch, define:

• batch_id
• goal
• included_steps
• critical_path_step
• parallel_lanes
• write_surfaces
• verification_commands
• review_gate
• completion_contract
• next_batch_if_pass
• fallback_if_fail

Do not execute a multi-step build sequence without first producing an explicit batch plan.

Phase 3: Ralph Loop State Machine

When execution mode is ralph_attended or ralph_overnight, use this loop:

1. Preflight
2. Batch Selection
3. Lane Plan
4. Implement
5. Verify
6. Review Gate
7. Fix / Retry
8. Integrate
9. Advance or Stop

Only advance when the current batch passes its binary gate.

Parallelization Rules

Parallelism is allowed only when it is safe.

Safe parallel lanes

Parallelize steps when they have:

• disjoint write scopes
• no unresolved dependency between them
• no shared ownership of fragile contract surfaces

Good sidecar lanes:

• read-only research
• documentation drafting
• isolated tests
• release notes
• audit and verification passes

Keep local on the critical path

Keep the following local unless the sequence explicitly isolates them:

• product-tier registries
• tool index / tool registration
• shared contracts used across many modules
• release and export manifests
• other single-owner integration surfaces

Subagent policy

Use subagents only for:

• independent sidecar lanes
• isolated implementation with disjoint write scope
• verification or review that does not block immediate local context-building

Do not delegate the immediate blocking task if the next local action depends on it.

Required Build-Step Fields

For build-oriented execution, each implementation step should define or be normalized into:

• id
• title
• depends_on
• required_capabilities
• write_scope
• verification
• integration_gate
• retry_budget
• handoff_contract

If these are missing, infer them conservatively. If they cannot be inferred safely, stop and emit a sequence-hardening recommendation.

Gate Policy

All meaningful completion decisions must be binary.

Allowed completion signals:

• tests passed
• verifier passed
• build succeeded
• review explicitly returned continue
• required artifact exists and matches the contract

Not sufficient on their own:

• "looks good"
• "seems fine"
• "mostly done"
• "probably works"

If verification is inconclusive, mark the batch inconclusive, explain why, and do not silently advance.

Audience Handling

After execution, outputs may be shaped for:

• humanize: explanation-first deliverables
• machinize: structured machine-readable outputs
• mixed: both

Do not ask about audience mode if the sequence or context already makes it obvious.

Output Contract

For each batch, return:

• batch_id
• steps_completed
• files_changed
• commands_run
• verification_results
• review_result
• blockers
• known_limitations
• next_executable_batch

For plan-oriented outputs, return:

• decision summary
• assumptions
• unresolved questions
• artifacts produced
• recommended next execution package

For build-oriented outputs, return:

• implementation summary
• exact verification steps
• pass/fail/inconclusive status
• next slice recommendation

Failure Handling

If a batch fails:

1. identify whether the failure is:
   • implementation
   • verification
   • environment
   • sequence-definition
2. apply the retry budget if appropriate
3. prefer narrow fixes over broad redesign
4. if still blocked, stop and emit:
   • blocker summary
   • affected batch
   • safe rollback or pause point
   • next required user or system action

Do not continue into the next batch after a failed gate.

Handoff to ReleaseChain / Launch

This skill is an orchestration substrate. It does NOT handle release-specific logic.

When build work completes successfully and outputs are in a reviewable state, offer the appropriate downstream skill:

Downstream need	Skill
Release (version, changelog, publish)	/skillweave-releasechain
Launch (deploy, communicate, go-live)	/skillweave-launch

Conditions

Hand off to releasechain when:

• Build-oriented work completed successfully
• Outputs are in a reviewable state
• The next logical step is review, test hardening, commit, release, or PR flow

Do not automatically transfer partial or inconclusive build batches.

Skill Boundaries

For complete role definitions, see:

• .skillweave/release/skill-boundaries.yaml — formal boundary specs
• skills/skillweave-releasechain/SKILL.md — releasechain skill doc
• skills/launch/SKILL.md — launch skill placeholder

Agent-Agnostic Execution

This skill is agent-agnostic.

It should prefer:

• capability-based routing
• lane-based task assignment
• central ownership of critical-path integration
• fallback to available agents when the preferred capability runner is unavailable

When multiple agents exist, assign by:

• capability fit
• write-scope safety
• dependency position
• verification needs

Do not encode vendor-specific assumptions into the execution logic.

Recommended Companion Files

Use these files if present:

• references/execution-rules.md
• references/format-spec.md
• references/sequence-type-detection.md
• references/parallel-execution.md
• references/ralph-loop-state-machine.md
• references/build-step-normalization.md
• references/gate-policy.md