@farazirfan/costar-server-executor 1.7.16 → 1.7.19

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

package/skills/skill-creator/SKILL.md

@@ -1,236 +0,0 @@
----
-name: skill-creator
-description: "Create new skills for the CoStar agent. Use when the user wants to add a new reusable capability, automate a workflow, or improve the agent's abilities. Also use when the agent identifies a repeating pattern that should be turned into a skill."
-metadata:
-  emoji: "🛠️"
-  always: true
-  skillKey: skill-creator
----
-
-# Skill Creator
-
-You can create new skills to extend your own capabilities. Skills are modular, reusable instructions that teach you how to handle specific tasks.
-
-## What is a Skill?
-
-A skill is a directory containing a `SKILL.md` file with:
-1. **YAML frontmatter** - metadata (name, description, requirements)
-2. **Markdown body** - detailed instructions for the agent to follow
-
-Skills can also include:
-- `scripts/` - executable scripts (Python, Bash, etc.)
-- `references/` - documentation files to load into context
-- `assets/` - templates, configs, or other files
-
-## Skill Locations
-
-Skills can be installed in three places:
-
-| Location | Path | Scope |
-|----------|------|-------|
-| **Workspace** | `<workspace>/skills/<name>/` | This agent only |
-| **Managed** | `~/.costar/skills/<name>/` | All agents on this machine |
-| **Bundled** | Shipped with the package | All installations |
-
-**Recommendation**: Create skills in the **workspace** (`skills/` subdirectory) for user-specific skills, or in **managed** (`~/.costar/skills/`) for skills that should persist across workspace resets.
-
-## Creating a New Skill
-
-### Step 1: Plan the Skill
-
-Before creating, consider:
-- **What task does it automate?** Be specific.
-- **What tools/commands does it need?** List required binaries, APIs, or env vars.
-- **Is it reusable?** Skills should handle a class of tasks, not one-off actions.
-- **What scripts or references would help?** Think about helper scripts.
-
-### Step 2: Create the Directory Structure
-
-```bash
-# For workspace skills:
-mkdir -p <workspace>/skills/<skill-name>
-
-# For managed skills (shared):
-mkdir -p ~/.costar/skills/<skill-name>
-```
-
-### Step 3: Write SKILL.md
-
-Create `SKILL.md` with this template:
-
-```markdown
----
-name: my-skill-name
-description: "Clear, one-line description of what this skill does and when to use it."
-metadata:
-  emoji: "🔧"
-  requires:
-    bins: ["required-binary"]
-    env: ["REQUIRED_ENV_VAR"]
-  install:
-    - kind: brew
-      formula: required-binary
-    - kind: npm
-      package: required-package
----
-
-# Skill Name
-
-## Overview
-Brief explanation of what this skill does.
-
-## Instructions
-Step-by-step instructions for the agent to follow when this skill is activated.
-
-### Step 1: ...
-### Step 2: ...
-
-## Examples
-Show example inputs and expected outputs.
-
-## Notes
-Any caveats, edge cases, or important considerations.
-```
-
-### Step 4: Add Resources (Optional)
-
-```
-my-skill/
-├── SKILL.md
-├── scripts/
-│   ├── helper.py      # Helper scripts
-│   └── setup.sh       # Setup script
-├── references/
-│   └── api-docs.md    # Reference documentation
-└── assets/
-    └── template.json  # Template files
-```
-
-### Step 5: Validate
-
-After creating the skill:
-1. Check it appears in the skills list (the agent will see it on next turn)
-2. Test it by asking the agent to use it
-3. Iterate on the instructions based on results
-
-## YAML Frontmatter Reference
-
-### Required Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | string | Unique skill identifier (lowercase, hyphens) |
-| `description` | string | When to use this skill (shown to agent) |
-
-### Optional Metadata Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `emoji` | string | Display emoji |
-| `always` | boolean | Always load (skip requirement checks) |
-| `skillKey` | string | Config key override |
-| `primaryEnv` | string | Primary API key env var |
-| `os` | string[] | Supported OS: `["darwin", "linux"]` |
-| `requires.bins` | string[] | Required binaries (all must exist) |
-| `requires.anyBins` | string[] | Required binaries (at least one) |
-| `requires.env` | string[] | Required environment variables |
-| `install` | array | Installation specs |
-
-### Install Specs
-
-```yaml
-install:
-  - kind: brew        # macOS Homebrew
-    formula: package-name
-  - kind: npm         # Node.js package
-    package: package-name
-  - kind: apt         # Debian/Ubuntu package
-    package: package-name
-  - kind: download    # Direct download
-    url: https://...
-    bins: ["binary-name"]
-```
-
-## Self-Improvement Guidelines
-
-When you notice a repeating pattern or workflow that could benefit from a skill:
-
-1. **Identify the pattern** - What steps are repeated? What's the common input/output?
-2. **Abstract it** - Generalize specific details into parameters
-3. **Create the skill** - Write clear, reusable instructions
-4. **Save it** - Put it in the workspace or managed skills directory
-5. **Announce it** - Tell the user you've created a new skill
-
-### Good Candidates for Skills
-- Multi-step workflows you've done more than twice
-- Complex tool chains (e.g., "search web → summarize → email results")
-- Domain-specific knowledge (e.g., "deploy to production checklist")
-- User-specific preferences (e.g., "format reports the way I like them")
-
-### Bad Candidates for Skills
-- One-off tasks
-- Simple single-tool operations
-- Tasks that change significantly each time
-
-## Examples of Well-Written Skills
-
-### Example: Daily Briefing Skill
-
-```markdown
----
-name: daily-briefing
-description: "Compile and send a daily briefing with calendar events, important emails, and task updates."
-metadata:
-  emoji: "📋"
-  requires:
-    env: ["GOOGLE_SERVICE_ACCOUNT_JSON"]
----
-
-# Daily Briefing
-
-## Instructions
-1. Get today's calendar events using get_calendar_events
-2. Search for unread important emails using search_emails
-3. Check pending cron jobs using cron tool status
-4. Compile into a concise briefing
-5. Send via message tool to the user
-
-## Format
-Subject: Daily Briefing - {date}
-
-📅 Calendar:
-- {event1}
-- {event2}
-
-📧 Important Emails:
-- {email1}
-- {email2}
-
-✅ Tasks:
-- {task1}
-```
-
-### Example: Code Review Skill
-
-```markdown
----
-name: code-review
-description: "Review code changes for bugs, style issues, and improvements."
-metadata:
-  emoji: "🔍"
-  requires:
-    bins: ["git"]
----
-
-# Code Review
-
-## Instructions
-1. Run `git diff` to see changes
-2. Analyze each file for:
-   - Bugs or logic errors
-   - Style inconsistencies
-   - Missing error handling
-   - Security issues
-3. Provide structured feedback with severity levels
-4. Suggest specific improvements with code examples
-```