alpaca-trading git:20260424.8d2549fA

Immutable. This exact content never changes and is served at /api/v1/blob/b6a96001de7cbf82.

---
name: alpaca-trading
description: Work safely in the Trading repository for Alpaca helpers, backtesting, journaling, scheduling, and related PowerShell modules. Prefer additive changes, preserve existing trading logic unless the user asks otherwise, and default to paper-trading-safe guidance.
---

# Alpaca Trading

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:

```text
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.

```powershell
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