@farazirfan/costar-server-executor 1.7.17 → 1.7.20

package/skills/trading/references/metals.md

@@ -0,0 +1,54 @@
+# Precious Metals Trading Reference
+
+> **This file is agent-editable.** Update it as you learn from real trades.
+
+## Gold (XAU/USD)
+
+- Safe haven — rallies during uncertainty and currency debasement
+- Inverse DXY correlation (-0.7 to -0.9)
+- Central banks are net buyers (structural demand floor)
+- Daily range: 1-3%, spikes 3-5% on crises
+
+## Silver (XAG/USD)
+
+- Dual role: precious metal + industrial (50% industrial demand)
+- Moves 1.5-2x gold's percentage move
+- Gold/Silver ratio: 60-80 range (above 80 = silver undervalued)
+
+## Data to Fetch via APIs
+
+- **Commodity quotes**: Gold, silver real-time prices
+- **Historical prices**: EOD for trend analysis
+- **Economic data**: Treasury rates (real yields = #1 gold driver), CPI
+- **Economic calendar**: FOMC, CPI, NFP dates
+- **Forex data**: DXY as leading indicator
+
+## Drivers
+
+### Bullish: Falling real yields, rising inflation, geopolitical crises, dollar weakness, central bank buying
+### Bearish: Rising real yields, strong dollar, risk-on sentiment, hawkish central banks
+
+## Strategies
+
+### Gold/Silver Ratio Trade
+- Above 85: buy silver, sell gold → close at 70-75
+- Below 65: buy gold, sell silver → close at 70-75
+- Historical win rate ~70% over 1-3 months
+
+### DXY Correlation Trade
+- DXY breakdown → buy gold. DXY breakout → short gold.
+
+### Macro Events
+- Dovish FOMC → buy gold. Hawkish → sell short-term.
+- CPI higher than expected → buy gold (inflation hedge)
+
+## Risk Rules
+
+- Size down during FOMC weeks
+- Don't fight strong DXY with long gold
+- Silver drops 30%+ in crashes (industrial collapse)
+- Weekend gap risk ($30-50 gold gaps)
+
+---
+
+*Last updated: Initial version. Agent should update after real metals trades.*

package/skills/trading/references/risk-management.md

@@ -0,0 +1,74 @@
+# Risk Management Reference
+
+> **Most important file.** Violating these rules is the primary reason traders lose. Agent-editable but only to make rules STRICTER, never looser.
+
+## Position Sizing
+
+```
+Position Size = (Account Balance x Risk %) / (Entry Price - Stop Loss Price)
+```
+
+Use `python3 scripts/position-sizer.py` for calculations.
+
+## Hard Limits (NEVER VIOLATE)
+
+| Rule | Limit | Action When Hit |
+|------|-------|-----------------|
+| Per-trade risk | 1% max | Reduce size or skip |
+| Total open risk | 3% | No new trades |
+| Daily loss | 2% | Stop for the day |
+| Weekly loss | 5% | Reduce sizes 50% |
+| Max drawdown | 10% | Pause, full review |
+| Critical drawdown | 15% | Stop trading, rebuild |
+
+## R:R Requirements
+
+| Quality | Min R:R |
+|---------|---------|
+| A+ (high confluence) | 2:1 |
+| B (moderate) | 3:1 |
+| C (speculative) | Skip it |
+
+## Stop-Loss Rules
+
+- Place at technical invalidation point BEFORE entry
+- NEVER move stop away from entry
+- Move to breakeven after 1R profit
+- Trail by 1.5-2 ATR for trend trades
+
+## Leverage
+
+| Asset | Max |
+|-------|-----|
+| Crypto spot | 1x |
+| Crypto futures | 3-5x |
+| Forex | 10-20x |
+| Stocks | 1-2x |
+| Gold/Silver | 5-10x |
+
+## Correlation: Max 2 same-direction on correlated assets (> 0.7)
+
+## Drawdown Recovery
+
+| Drawdown | Action |
+|----------|--------|
+| 0-3% | Normal |
+| 3-5% | -25% size, A+ only |
+| 5-8% | -50% size, 1 trade/day |
+| 8-10% | Paper trade, review |
+| 10%+ | Full stop |
+
+## Pre-Trade Checklist
+
+```
+[ ] Regime identified?  [ ] 2+ confluence signals?
+[ ] R:R >= 2:1?         [ ] Risk <= 1%?
+[ ] Open risk < 3%?     [ ] Not correlated?
+[ ] Stop at tech level? [ ] No news in 2h?
+```
+
+ANY check fails → DO NOT TRADE.
+
+---
+
+*Agent may make rules STRICTER only. NEVER looser.*

package/skills/trading/references/stocks.md

@@ -0,0 +1,74 @@
+# Stocks Trading Reference
+
+> **This file is agent-editable.** Update it as you learn from real trades.
+
+## Market Characteristics
+
+- Regular hours: NYSE/NASDAQ 9:30-16:00 ET, Mon-Fri
+- Pre-market 4:00-9:30 ET, After-hours 16:00-20:00 ET
+- Fundamentals + sentiment drive price
+- Index moves (SPY/QQQ) drag individual stocks
+- Sector rotation is a major theme
+
+## Key Indices
+
+| Index | Tracks | Signal |
+|-------|--------|--------|
+| SPY | S&P 500 large-cap | Broad market health |
+| QQQ | NASDAQ 100 tech | Growth/tech sentiment |
+| IWM | Russell 2000 small-cap | Risk appetite |
+| VIX | Implied volatility | Fear gauge (> 25 = fear) |
+
+## Data to Fetch via APIs
+
+Your FMP APIs give you massive edge here:
+- **Stock quotes**: real-time, after-hours, batch
+- **Historical prices**: EOD and intraday (1min-4hr)
+- **Technical indicators**: SMA, EMA, RSI, MACD, Williams, ADX from API directly
+- **Fundamentals**: Income statements, balance sheets, key metrics, financial scores
+- **Earnings**: Calendar, estimates, transcripts, surprises
+- **Analyst data**: Ratings, price targets, grades, consensus
+- **Institutional**: 13F filings, insider trades, fund holdings
+- **Market breadth**: Sector performance, gainers/losers, most active
+- **Screener**: Filter by 100+ criteria
+- **News**: Stock-specific news, press releases
+
+## Key Signals
+
+### Market Internals
+- Advance/Decline: more advancing = healthy rally
+- % above 200 SMA: > 60% bullish, < 40% bearish
+- VIX term structure: contango = complacent, backwardation = panic
+
+### Sector Rotation Cycle
+- Early expansion: tech, consumer discretionary
+- Mid: industrials, materials
+- Late: energy, staples
+- Recession: utilities, healthcare
+
+### Earnings
+- Guidance matters more than results
+- Pre-earnings: IV rises, range-bound
+- Post-earnings: gap based on beat/miss vs expectations
+
+## Stock-Specific Strategies
+
+### Relative Strength
+- Buy stocks outperforming sector AND SPY on pullbacks to 20 EMA
+
+### Gap and Go
+- Pre-market gaps > 3% on volume → trade first candle break
+
+### ETF Sector Rotation
+- Buy top 2-3 sectors by relative performance, avoid bottom 2-3
+
+## Risk Rules (Stock-Specific)
+
+- No single stock > 5% of portfolio
+- Cut size 50% before earnings
+- PDT rule: < $25K = max 3 day trades per 5 days
+- Avoid penny stocks under $5
+
+---
+
+*Last updated: Initial version. Agent should update after real stock trades.*

package/skills/trading/references/strategies.md

@@ -0,0 +1,98 @@
+# Trading Strategies Reference
+
+> **This file is agent-editable.** Add new strategies you discover, refine existing ones based on performance, mark declining strategies.
+
+## Strategy Selection
+
+| Timeframe | Trending | Ranging | High Volatility |
+|-----------|----------|---------|-----------------|
+| Scalp (min) | Momentum scalp | Range scalp | Avoid |
+| Day (hours) | Breakout, trend-follow | Mean reversion, VWAP | News fade |
+| Swing (days) | Momentum, breakout | S/R bounce | Vol contraction |
+| Position (weeks) | Trend-follow, macro | Accumulation | Hedged |
+
+---
+
+## Day Trading
+
+### Breakout
+- Consolidation → volume spike > 2x on break → enter on candle CLOSE
+- Stop below range, target = measured move (range height)
+
+### VWAP Mean Reversion
+- Extended deviation from VWAP → reversion entry with RSI divergence
+- Avoid strong trending days
+
+### Opening Range Breakout (ORB)
+- First 15-30 min high/low → trade the break, stop at opposite side
+- Filter: trade in direction of pre-market bias
+
+---
+
+## Swing Trading
+
+### EMA Trend Following
+- Price > 20 > 50 > 200 EMA → buy pullback to 20 EMA
+- Stop below 50 EMA, target previous high or 2-3x risk, hold 3-15 days
+
+### Support/Resistance Bounce
+- Bounce at S/R with candlestick confirmation, stop 0.5-1% beyond level
+
+### Fibonacci Retracement
+- Key levels: 38.2%, 50%, 61.8% — enter at confluence with S/R + EMA
+- Stop below 78.6%
+
+---
+
+## Momentum
+
+### Relative Strength
+- Buy top 20% RS ranking on pullbacks, exit when RS drops below 50th pctile
+
+### MACD Momentum
+- MACD crosses signal + histogram growing + price above EMA → enter
+
+---
+
+## Mean Reversion
+
+### RSI Extreme
+- Long: RSI < 25 crosses back above 30. Short: RSI > 75 crosses below 70
+- Avoid in strong trends
+
+### Bollinger Squeeze
+- Bands contract → breakout imminent → trade the direction when bands expand
+
+---
+
+## Arbitrage
+
+### Cross-Exchange (Crypto)
+- Same asset different prices → buy cheap, sell expensive simultaneously
+
+### Pairs/Statistical
+- Correlated assets diverge → long underperformer, short outperformer → close on mean reversion
+
+---
+
+## News/Events
+
+### Scheduled Events
+- Wait 5-15 min post-release, trade new direction after noise settles
+
+### Earnings Gap (Stocks)
+- Gap with trend = trade it. Gap against = wait (60%+ fill rate). 0.5% max risk.
+
+---
+
+## Rules
+
+1. Max 2 strategies simultaneously on same asset
+2. Strategies must confirm, not contradict
+3. If indicators conflict → stay flat
+4. Track each strategy separately in LEARNING.md
+5. Retire strategies declining over 20+ trades
+
+---
+
+*Last updated: Initial version. Agent should add and refine based on real performance.*

package/skills/trading/scripts/position-sizer.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+Position Sizer - Calculate exact position size based on risk parameters.
+
+Usage:
+  python3 scripts/position-sizer.py --account 1000 --risk-pct 1 --entry 50000 --stop 48500
+  python3 scripts/position-sizer.py --account 1000 --risk-pct 1 --entry 50000 --stop 48500 --target 53000
+  python3 scripts/position-sizer.py --account 1000 --risk-pct 1 --entry 50000 --stop 48500 --leverage 5
+
+Output: Position size, dollar risk, units, and trade validation.
+"""
+
+import json
+import sys
+import argparse
+
+
+def calculate_position(account, risk_pct, entry, stop, target=None, leverage=1):
+    """Calculate position size and trade parameters."""
+    # Validate inputs
+    if account <= 0:
+        return {"error": "Account balance must be positive"}
+    if risk_pct <= 0 or risk_pct > 5:
+        return {"error": "Risk percentage must be between 0 and 5%"}
+    if entry <= 0 or stop <= 0:
+        return {"error": "Entry and stop prices must be positive"}
+    if entry == stop:
+        return {"error": "Entry and stop cannot be the same price"}
+
+    # Determine direction
+    is_long = stop < entry
+    direction = "LONG" if is_long else "SHORT"
+
+    # Calculate risk per unit
+    risk_per_unit = abs(entry - stop)
+    risk_pct_of_entry = risk_per_unit / entry * 100
+
+    # Dollar risk
+    dollar_risk = account * (risk_pct / 100)
+
+    # Position size (in units of the asset)
+    units = dollar_risk / risk_per_unit
+
+    # Position value (in dollars)
+    position_value = units * entry
+
+    # Account percentage used
+    account_pct_used = position_value / account * 100
+
+    # With leverage
+    margin_required = position_value / leverage
+    margin_pct = margin_required / account * 100
+
+    result = {
+        "direction": direction,
+        "entry_price": entry,
+        "stop_loss": stop,
+        "risk_per_unit": round(risk_per_unit, 6),
+        "risk_pct_of_entry": round(risk_pct_of_entry, 2),
+        "dollar_risk": round(dollar_risk, 2),
+        "units": round(units, 8),
+        "position_value": round(position_value, 2),
+        "account_pct_used": round(account_pct_used, 2),
+        "leverage": leverage,
+        "margin_required": round(margin_required, 2),
+        "margin_pct_of_account": round(margin_pct, 2),
+    }
+
+    # Take-profit analysis
+    if target:
+        reward_per_unit = abs(target - entry)
+        reward_dollars = units * reward_per_unit
+        rr_ratio = reward_per_unit / risk_per_unit
+
+        result["take_profit"] = target
+        result["reward_per_unit"] = round(reward_per_unit, 6)
+        result["reward_dollars"] = round(reward_dollars, 2)
+        result["risk_reward_ratio"] = round(rr_ratio, 2)
+        result["rr_assessment"] = (
+            "EXCELLENT" if rr_ratio >= 3 else
+            "GOOD" if rr_ratio >= 2 else
+            "ACCEPTABLE" if rr_ratio >= 1.5 else
+            "POOR - DO NOT TAKE"
+        )
+
+        # Breakeven win rate needed
+        breakeven_wr = 1 / (1 + rr_ratio) * 100
+        result["breakeven_win_rate"] = round(breakeven_wr, 1)
+
+    # Validation warnings
+    warnings = []
+
+    if risk_pct > 2:
+        warnings.append("RISK TOO HIGH: Risking more than 2% per trade. Reduce to 1% or less.")
+    if account_pct_used > 30 and leverage == 1:
+        warnings.append(f"LARGE POSITION: Using {account_pct_used:.1f}% of account on one trade.")
+    if margin_pct > 50:
+        warnings.append(f"HIGH MARGIN: Using {margin_pct:.1f}% of account as margin.")
+    if leverage > 10:
+        warnings.append(f"EXTREME LEVERAGE: {leverage}x leverage is very risky.")
+    if target and result.get("risk_reward_ratio", 0) < 2:
+        warnings.append(f"LOW R:R: {result['risk_reward_ratio']}:1 is below minimum 2:1 threshold.")
+
+    result["warnings"] = warnings
+    result["trade_approved"] = len([w for w in warnings if "TOO HIGH" in w or "DO NOT TAKE" in w or "EXTREME" in w]) == 0
+
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Calculate trading position size")
+    parser.add_argument("--account", type=float, required=True, help="Account balance in USD")
+    parser.add_argument("--risk-pct", type=float, required=True, help="Risk percentage per trade (e.g., 1 for 1%%)")
+    parser.add_argument("--entry", type=float, required=True, help="Entry price")
+    parser.add_argument("--stop", type=float, required=True, help="Stop-loss price")
+    parser.add_argument("--target", type=float, help="Take-profit price (optional)")
+    parser.add_argument("--leverage", type=float, default=1, help="Leverage multiplier (default: 1)")
+
+    args = parser.parse_args()
+    result = calculate_position(args.account, args.risk_pct, args.entry, args.stop, args.target, args.leverage)
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/skills/commit/SKILL.md

@@ -1,69 +0,0 @@
----
-name: commit
-description: Create git commits with proper formatting and commit messages. Follows Conventional Commits standard.
-homepage: https://www.conventionalcommits.org/
-metadata:
-  emoji: "📝"
-  requires:
-    bins: ["git"]
----
-
-# Commit Skill
-
-Create well-formatted git commits following best practices.
-
-## Usage
-
-Before committing:
-1. Check git status to see what's changed
-2. Review the diff to understand changes
-3. Stage only related files together
-4. Write clear, concise commit messages
-
-## Commit Message Format
-
-Follow Conventional Commits:
-
-```
-<type>(<scope>): <description>
-
-[optional body]
-
-[optional footer]
-```
-
-Types:
-- `feat`: New feature
-- `fix`: Bug fix
-- `docs`: Documentation
-- `style`: Formatting (no code change)
-- `refactor`: Code refactoring
-- `test`: Adding tests
-- `chore`: Maintenance
-
-## Examples
-
-Simple commit:
-```bash
-git add src/tools/new-tool.ts
-git commit -m "feat(tools): add new-tool for API calls"
-```
-
-Commit with body:
-```bash
-git commit -m "fix(auth): handle expired tokens
-
-Tokens are now refreshed automatically when they expire.
-Previously this would cause auth failures.
-
-Fixes #123"
-```
-
-## Best Practices
-
-1. **Atomic commits**: Each commit should be a single logical change
-2. **Clear messages**: Describe what and why, not how
-3. **Present tense**: "Add feature" not "Added feature"
-4. **Imperative mood**: "Fix bug" not "Fixes bug"
-5. **Reference issues**: Include issue numbers when relevant
-6. **Review before commit**: Always check `git diff --staged`

package/skills/review-pr/SKILL.md

@@ -1,105 +0,0 @@
----
-name: review-pr
-description: Review pull requests using GitHub CLI. Check code changes, CI status, and provide feedback.
-homepage: https://cli.github.com/manual/gh_pr
-metadata:
-  emoji: "👀"
-  requires:
-    bins: ["gh"]
-  install:
-    - id: brew
-      kind: brew
-      formula: gh
-      bins: ["gh"]
-      label: "Install GitHub CLI (brew)"
-    - id: apt
-      kind: apt
-      package: gh
-      bins: ["gh"]
-      label: "Install GitHub CLI (apt)"
----
-
-# Review PR Skill
-
-Review pull requests efficiently using GitHub CLI.
-
-## Viewing PRs
-
-**List open PRs:**
-```bash
-gh pr list
-```
-
-**View specific PR:**
-```bash
-gh pr view 123
-```
-
-**View PR diff:**
-```bash
-gh pr diff 123
-```
-
-**Checkout PR locally:**
-```bash
-gh pr checkout 123
-```
-
-## Checking CI Status
-
-**View checks:**
-```bash
-gh pr checks 123
-```
-
-**Watch checks (live updates):**
-```bash
-gh pr checks 123 --watch
-```
-
-## Reviewing
-
-**View review comments:**
-```bash
-gh pr view 123 --comments
-```
-
-**Leave review comment:**
-```bash
-gh pr review 123 --comment --body "LGTM!"
-```
-
-**Request changes:**
-```bash
-gh pr review 123 --request-changes --body "Please fix..."
-```
-
-**Approve:**
-```bash
-gh pr review 123 --approve
-```
-
-## Best Practices
-
-1. **Check CI first**: Ensure tests pass before detailed review
-2. **Review diff**: Look at `gh pr diff` for context
-3. **Test locally**: Check out the PR if needed
-4. **Constructive feedback**: Be specific and helpful
-5. **Approve or request changes**: Don't leave hanging PRs
-
-## Advanced
-
-**View specific files:**
-```bash
-gh pr diff 123 --name-only
-```
-
-**Check review status:**
-```bash
-gh pr view 123 --json reviewDecision
-```
-
-**Merge after approval:**
-```bash
-gh pr merge 123 --squash
-```