Alpaca Trading

Intent

Support safe paper trading, Alpaca automation, broker workflow analysis, and Trading repo changes without increasing live trading risk.

Do Not Use When

• Do not use for financial advice, guaranteed performance claims, live order execution without explicit user instruction, or unrelated trading platforms.
• Required context is missing and cannot be reasonably inferred.
• A more specific skill in this repo is a better match.

Use this skill when the user is working in the Trading repository on Alpaca-connected scripts, backtesting workflows, journaling, scheduling, or reusable PowerShell Alpaca modules.

Trigger When

• The user mentions the Trading repo, Alpaca scripts, paper trading, backtesting, journaling, scheduler jobs, or Alpaca PowerShell modules.
• The task touches Alpaca/, Backtesting/, Journal/, Scheduler/, src/, Tests/, rsi_macd_bot/, or btc-signal-executor/.
• The user wants to build, extend, debug, document, test, or review repo workflows around Alpaca trading.

Repo Shape

The current repository is a mixed Python and PowerShell project with these main areas:

Trading/
|-- Alpaca/
|-- Backtesting/
|-- Journal/
|-- Scheduler/
|-- src/
|-- Tests/
|-- rsi_macd_bot/
`-- btc-signal-executor/

Use the existing structure instead of inventing a new module layout.

Default Behavior

• Preserve what already exists unless the user asks for a larger redesign.
• Prefer additive scaffolding over speculative rewrites of trading logic.
• Default to paper-trading-safe patterns and make live-trading risk explicit.
• Keep API secrets in environment variables or existing repo config flows, never hardcoded.
• Align with the repo's existing GitHub Spec workflow for non-trivial changes.

Workflow

1. Identify which existing repo area the change belongs to.
2. Read the nearby README, script, or module before proposing changes.
3. Reuse current patterns for Python, PowerShell, logging, and tests.
4. For non-trivial work, follow the repo workflow: requirements, spec, plan, tasks, implementation, audit, regression test.
5. Prefer paper-trading examples unless the user explicitly asks for live-trading support.
6. If live-trading code is requested, require explicit confirmation patterns and keep the safety guard intact.
7. Update docs and tests alongside behavior changes.

Safety Rules

• Default to the Alpaca paper endpoint unless the user explicitly requests live trading.
• Never remove a live-trading confirmation guard from real-money scripts.
• Treat AI analysis as advisory only. Do not let model output directly trigger order placement without deterministic code checks.
• Log trade actions and failures using the repo's existing logging and journal patterns.
• Call out when a request would move from paper trading into live execution risk.

Implementation Notes

Python And PowerShell

• The repo is mixed-stack. Do not force everything into one language.
• Alpaca/ contains existing paper-trading helpers.
• src/ contains reusable PowerShell Alpaca modules such as auth, config, market data, risk, orders, positions, and account helpers.
• Tests/ contains Python and PowerShell verification coverage.

Live Trading Guard

If a script can send live orders, include an explicit confirmation gate and make the live path opt-in.

param(
    [switch]$LiveTrading
)

if ($LiveTrading) {
    $Confirm = Read-Host "Type CONFIRM to proceed with live trading"
    if ($Confirm -ne "CONFIRM") {
        exit 0
    }
}

AI Coaching Pattern

If AI analysis is added, keep it advisory:

• AI returns a labeled assessment such as BULLISH, BEARISH, or NEUTRAL
• deterministic code applies risk checks and order rules
• model output alone must not place an order

Constraints

• Do not invent folders like PaperTrading, LiveTrading, TradeJournal, or AICoaching if the work belongs in the current repo structure.
• Do not hardcode credentials.
• Do not rewrite business logic just to modernize style.
• Do not describe the repo as a Claude-only system; it is a general trading repo with Claude-relevant integrations.

References

• Root repo guide: Trading/README.md
• GitHub Spec baseline: Trading/specs/001-core-trading-foundation/
• Copilot instructions already present in the repo: Trading/.github/copilot-instructions.md

Validation Checklist

• Repo area matches the real Trading repository layout
• Paper trading is the default path in examples and guidance
• Live trading remains explicit and guarded
• Secrets are sourced from environment variables or existing config flows
• Changes preserve existing trading logic unless requested otherwise
• Docs and tests are updated when behavior changes

Help And Examples

If the user is not sure how to use this skill, asks what it needs, or asks for examples:

• Explain in plain language what this skill can do.
• Tell the user the minimum input needed for a useful first pass.
• Show the example prompts below.
• Offer the fastest next prompt the user can send.

Minimum useful input:

• A trading goal, repo context, or strategy question plus any symbols, timeframes, or risk rules that matter.

Example prompts:

• Use alpaca-trading to review my Trading repo and tell me the safest way to add bracket orders.
• Help me build an Alpaca paper trading workflow for SPY with clear entry, exit, and risk rules.
• Show me how to use this skill for a repo level trading automation plan.