alphacouncil-agent 0.5.0

package/skills/alphacouncil-agent/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: alphacouncil-agent
+description: Use AlphaCouncil Agent for listed-equity research workflows that need multiple Codex subagents, shared evidence packets, public-equity analysis, banking/event analysis, filings/news search, valuation, long/short pitch work, risk debate, or portfolio-manager style decisions.
+---
+
+# AlphaCouncil Agent
+
+Use this plugin when the user invokes `@alphacouncil-agent` or asks for a multi-agent public-equity research workflow.
+
+## Agent-Skills Governance
+
+Also apply `../agent-skills-governance/SKILL.md` before planning, running, synthesizing, or reporting. That bundled skill provides the agent-skills-style anti-laziness gates for every installer of this plugin; it is not a separate local dependency.
+
+## Mandatory Council Contract (MUST READ FIRST)
+
+You MUST run the full multi-agent council before giving any final answer. This is not optional and cannot be shortcut.
+
+- You MUST run ALL 11 evidence roles (`market_data`, `earnings_deep_dive`, `forward_expectations`, `sell_side_revisions`, `earnings_call_transcript`, `quant_factor`, `valuation_long_short`, `news_industry_management`, `management_industry_voices`, `insider_sec`, `ib_event_analysis`), THEN `bull_researcher`, THEN `bear_researcher`, THEN `portfolio_manager` — in that order.
+- You MUST NOT answer single-pass from your own model knowledge. You MUST NOT skip analysts, and you MUST NOT call `plan_visible_run` and then immediately record a `portfolio_manager` decision without first recording every planned evidence packet and both debate researchers.
+- A run is "complete" ONLY when every planned evidence task is recorded/completed AND `bull_researcher` and `bear_researcher` and `portfolio_manager` are all recorded. Anything less is INCOMPLETE.
+- The MCP server enforces this. If you record the `portfolio_manager` decision while any planned evidence packet or either debate researcher is missing, the server marks the run `status=incomplete` (NOT `complete`) and prepends a visible INCOMPLETE banner to `final_report.md`. Do not present an incomplete run as a finished investment decision.
+
+## Preflight Interaction
+
+Do not ask startup option questions by default. For underspecified requests such as `@alphacouncil-agent 帮我看看 NOK`, infer:
+
+- language: user's apparent language
+- goal: entry/actionability judgment
+- horizon: include short-term 1-4 weeks, medium-term 3-6 months, and long-term 12 months in the final report
+
+Ask only when the user explicitly requests option selection before launch. Use the inferred language for visible main-thread preflight/progress updates, visible agent prompts, evidence packets, debate packets, and final synthesis unless the user explicitly requests another language. Always pass the original user request in `prompt`, and pass the inferred language as `language` to AlphaCouncil Agent MCP tools.
+
+## Stage 0 — Ask which council to run (every host)
+
+**Before planning a run, call `list_council_options` and let the user choose.**
+
+A council is anywhere from 7 to 44 seats. That range is the user's time and money, and
+choosing silently is wrong in both directions: pick small and the bench they were promised
+never runs, pick everything and a one-line question costs a full fan-out.
+
+Present the three presets with their seat counts and relative cost, and say that they can
+instead name individual analysts and a master roster. Then wait for the answer.
+
+**Do not ask when they have already told you.** A user who named a roster, said "run
+everything", said "just be quick", or is repeating a run with the same shape has answered;
+asking again is an interruption, not diligence.
+
+How to ask, per host:
+
+- **Claude Code** — use `AskUserQuestion` with the presets as options.
+- **Codex, OpenCode, Grok Build** — ask in chat as a short numbered list and wait for a reply.
+
+Two things to say plainly when you ask:
+
+- The estimates are relative magnitudes, not promises. "Roughly three times the seats" is
+  honest; "about 33 minutes" is not.
+- If they choose everything, say once that it will be noticeably slower — then run it. They
+  are allowed to spend their own time; they are not required to guess what it costs.
+
+## Visible-First Workflow
+
+Use visible Codex subagents whenever the user asks to see subagents, asks for a chat-style analyst team, says child agents must be visible, or invokes `@alphacouncil-agent` for an investment decision without explicitly requesting headless/background mode.
+
+Default to the full workflow. Do not downgrade to a lite/smoke/visible-only summary unless the user explicitly asks for lite, smoke test, or debug output. Do not describe the final user-facing report as "visible version", "lite", "smoke", or "debug"; those are execution details, not investment-report content.
+
+1. If `multi_agent_v1.spawn_agent` is available, spawn separate visible agents for the full default analyst team:
+<!-- generated:roster start -->
+   - `macro_regime`
+   - `market_data`
+   - `earnings_deep_dive`
+   - `forward_expectations`
+   - `quant_factor`
+   - `valuation_long_short`
+   - `news_industry_management`
+   - `market_narrative`
+   - `social_pulse`
+   - `insider_sec`
+   - `ib_event_analysis`
+   - `bull_researcher`
+   - `bear_researcher`
+   - `portfolio_manager`
+<!-- generated:roster end -->
+2. Give each visible agent a narrow prompt and require JSON evidence or debate output. Tell each agent not to call `alphacouncil-agent` recursively.
+3. Use the selected or inferred language for visible agent prompts, evidence packets, debate packets, and final synthesis. Keep JSON field names in English.
+4. **Master bench — runs on every host, not only Claude Code.** After the evidence agents finish and before the debate, pass `masters_roster` or `masters` to `plan_visible_run` and run each selected lens. Each master reads the SAME established facts the analysts read plus the analyst packets, and returns one JSON opinion recorded with `record_master_opinion(run_id, master, packet)`.
+   - Default roster when the user does not choose: `masters-core`.
+   - A master whose method cannot judge this name returns `stance: "out_of_scope"`. That is a conclusion, not an abstention, and it carries zero weight rather than being coerced into a view.
+   - **The run is `incomplete` until every selected master has reported.** A bench nobody consulted is worse than no bench: the reader believes the verdict survived every lens when it survived none.
+   - Feed the masters' disagreements into the bull and bear prompts. Their disagreement is the point; a bench that agrees with the analysts has added nothing.
+5. **Verifiers — also every host.** Build a claim ledger from the merged packets, take only thesis-bearing claims, and run `source_fidelity`, `rederivation` and `refuter` against each. Record each with `record_verifier_verdict(run_id, verifier, seat, verdict, claim)`.
+   - Failed verification **down-weights the seat that made the claim** in the PM synthesis; a seat is never silently erased.
+   - `cannot_confirm` and `stands` are real results. Manufacturing a `weakened` verdict to look diligent lowers a seat's weight for no reason, and weight moves the final rating.
+6. Wait for the evidence agents, merge their outputs into a shared evidence set in the main thread, then run bull, bear, and portfolio-manager agents.
+   - Round 1: bull writes the long case; bear writes the short case.
+   - Round 2: pass bull's packet to bear for rebuttal, and bear's packet to bull for rebuttal.
+   - Round 3: each side asks three questions; the other side answers them.
+   - Final: portfolio_manager reads evidence plus all debate rounds and decides whether bull, bear, or balanced won.
+7. Return a concise but evidence-rich user handoff in the selected or inferred language: rating, debate winner, key earnings/financial results, forward expectations or event thresholds, important news/industry signals, valuation range, position guidance, top invalidation conditions, and saved file locations. Do not paste an overlong report into chat unless the user asks for the full body inline. The saved `final_report.md` must still be complete enough to read without opening artifacts: include each evidence analyst's summary, key data/news/filing/quant findings, the bull case, bear case, rebuttals/questions where available, portfolio-manager verdict, data gaps, and source table. Include links/paths to saved artifacts in the handoff.
+   - If the Data Analytics `datascienceWidgets` tools are available, also create a real dashboard/report artifact from the completed evidence and decision: call `validate_artifact` first, then `render_artifact`. Do not treat `output_mode=data_analytics` as only a prose style.
+   - If Documents, PDF, Spreadsheets, or Presentations are requested as output formats, use their plugin/skill workflow as a delivery layer after the investment decision is complete; do not move investment judgment into those format plugins.
+8. If the user specifically wants left-sidebar Codex chat threads, use `codex_app.list_projects` and `codex_app.create_thread` instead of MCP headless execution. Create one thread per major role and report the created thread IDs.
+9. Do not treat `plan_visible_run` as execution. It only creates the run envelope and prompts; visible agents/threads must actually be created and read before final synthesis.
+
+## Data Tools — call these instead of searching
+
+Every tool below is keyless. **A number these can supply must never come from a search
+result, from a summary, or from memory.** Search is for what the tools cannot reach:
+explanation, guidance, competitor commentary, and anything not yet filed.
+
+| Need | Call | Notes |
+|---|---|---|
+| Price | `get_quote` | Delayed ~15m. Say so wherever a level matters. |
+| Filings-based quality screen | `screen_ticker` | Pass `ticker`; the CIK is resolved for you. A rule whose inputs are missing is `skipped`, **never a pass**. |
+| Screen a list | `screen_candidates` | Capped at 40; a fetch failure is `unavailable`, not an elimination. |
+| Full US filer list | `list_us_universe` | SEC `company_tickers.json`. |
+| Non-US financials | `market_financials`, `market_coverage` | TWSE keyless; KR/JP need a free key; HK/CN are documents only. Check coverage **before** promising a number. |
+| Macro context | `get_macro_snapshot` | 21 series, 5 derived. Observations, not a regime call. |
+| Options positioning | `get_options_chain` | IV term structure, 25-delta skew, put/call ratios, open-interest concentration. |
+| Dated news and filings | `get_news` | `symbol`, `query` and/or `cik`. Undated items are excluded, not shown as recent. |
+| What the market is talking about | `get_market_narrative` | Themes ranked by coverage, each paired with the series that would corroborate it. |
+| Retail and technical chatter | `get_social_pulse` | Reddit, Hacker News, Bluesky. |
+| Confirm a quoted X post | `verify_x_post` | A decoded timestamp proves nothing; any invented id decodes to a plausible date. |
+| Industry map | `industry_brief`, `industry_peers`, `industry_coverage` | Ask coverage first — it says whether the participant list is authoritative. |
+| Facts + brief in one call | `compose_research_brief` | Grounding for a whole run. |
+
+### Limits you must carry into the report, not discover later
+
+- **IV percentile is not computable.** The chain is a snapshot with no history. Any claim that
+  volatility is high or low versus its own past goes in `open_questions`.
+- **X / Twitter has no free discovery channel.** Professional FinTwit is **not** covered and
+  Reddit is not a substitute. Say so rather than implying you looked at social media.
+- **Non-US names have no options chain here** and often no structured financials. Report the
+  gap; never substitute a US peer's numbers.
+- **A skipped screen rule is a gap.** Reporting `6/7 passed` without naming the seventh
+  misrepresents the screen.
+
+## Headless MCP Workflow
+
+Use MCP only when the user explicitly accepts background/headless execution, wants saved files, or asks to inspect/re-run a previous saved run.
+
+1. Call `collect_evidence` when the request needs source gathering and file artifacts.
+2. Call `analyze_symbol` when the user wants a complete long/short or portfolio decision saved under `~/.alphacouncil-agent/runs/`.
+3. Call `read_run` to inspect a saved evidence run.
+4. Headless MCP defaults to real `codex exec` workers. Pass `dry_run=true` only for explicit planning/self-test requests, not for a user-requested stock analysis.
+5. Do not describe MCP `codex exec` workers as visible chat subagents. They are background workers with `status.json`, `events.jsonl`, and `all_agents.md`.
+
+## Claude Code Parallel Path
+
+Use this path when running under Claude Code with the Task tool available. It reuses the exact same MCP run envelope and recording tools as the Visible-First and Headless workflows above; only the executor and the gating change. If the Task tool is NOT available, fall back to the Visible-First Workflow (or Headless MCP), and say so plainly per the fail-closed visibility rule.
+
+Detect capability first: if you can emit `Task` subagent calls in one turn, prefer this path over the sequential fallback. Otherwise do not claim a parallel council ran.
+
+### Model policy (cost-aware)
+
+Opus on every subagent is expensive. Default to a tiered policy, and let the user override at launch:
+
+- **Evidence analysts (Stage 1) and verifiers (Stage 2b)** → a fast, cheaper model (**Sonnet 4.6**, or **Haiku** for pure fetch/extract). These are bounded source-gathering jobs.
+- **Bull/bear debate (Stage 3) and `portfolio_manager` verdict (Stage 4)** → the strongest model (**Opus 4.8**), because these carry the reasoning.
+
+Default is "evidence on Sonnet, debate/verdict on Opus 4.8". Ask once at launch only to offer overrides ("all Opus" for max depth, "all Sonnet" for max thrift); otherwise use the default tiering. Set the model per `Task` subagent (`model:` option). If the host cannot set per-subagent models, say so and proceed on the host default.
+
+### Language
+
+Detect the user's language from their request and propagate it to EVERY subagent: each `Task` prompt, the evidence/debate/verdict content the subagents produce, and all workflow progress text shown in the main thread must be in that language (Chinese in -> Chinese throughout; Japanese in -> Japanese throughout). Keep JSON field names and role keys in English; translate values and prose. This matches the Preflight language rule.
+
+
+### Stage 0 — Plan (envelope only)
+Call `plan_visible_run` with `symbol`, `prompt` (original user request), `as_of`, and inferred `language`. It returns `run_id`, the 11 evidence agent specs, the 3 debate agent specs, and artifact paths. This is planning only (SKILL step 7); do not treat it as execution.
+
+### Stage 1 — Evidence fan-out (one turn, isolated context)
+In a SINGLE assistant turn, emit 11 `Task` (subagent_type: general-purpose) calls, one per evidence role: `market_data`, `earnings_deep_dive`, `forward_expectations`, `sell_side_revisions`, `earnings_call_transcript`, `quant_factor`, `valuation_long_short`, `news_industry_management`, `management_industry_voices`, `insider_sec`, `ib_event_analysis`. Each subagent:
+- May use ONLY `WebSearch` + `WebFetch`. It must NOT call `@alphacouncil-agent`, `collect_evidence`, `analyze_symbol`, or `read_run` (leaf-worker rule, Boundaries).
+- Runs a query ladder: a primary-locator search (use `allowed_domains` such as `sec.gov` and the company IR/exchange domain), a dated recency search, and one mandatory disconfirming search (e.g. `<ticker> guidance cut`, `downgrade`, `accounting concern`).
+- WebFetches the actual primary doc where one exists (insider_sec -> EDGAR full-text + Form 4; earnings_deep_dive / earnings_call_transcript -> 8-K Ex-99.1 / IR transcript; ib_event_analysis -> 8-K / 424B / deal release; market_data -> exchange/quote page) and quotes exact figures with real dates.
+- Returns exactly one JSON evidence packet matching the Agent Output Contract, with a real `url` and `published_at` on every source and every paywalled/missing/stale item routed into `open_questions`.
+
+### Stage 2 — Collect + barrier
+As each Task returns, call `record_visible_packet(run_id, task, packet, thread_id=<subagent id>)`. The server upserts by `task`, rescopes sources to `<task>:S1`, rewrites `source_manifest.json` + `all_agents.md`, and flips the run phase toward `visible_debate`. HARD GATE: do not start debate until all 11 packets are recorded (assert each `task` is completed or explicitly degraded; poll `status.json` if needed). Proceeding with k<11 violates the barrier.
+
+### Stage 2b — Adversarial verify + repair (loop-until-dry, max 2 rounds)
+Build a claim ledger from the merged packets (only non-low / thesis-bearing claims are "material"). For each material claim, fan out up to 3 verifier `Task` subagents in one turn, each with fresh context and seeing only the bare claim + ticker:
+- source_fidelity: `WebFetch` the exact cited URL; return supported | partial | contradicted | source_unreachable | source_does_not_mention.
+- rederivation: find the fact fresh from OTHER sources; return agree | disagree | cannot_confirm with a new source.
+- refuter: search for disconfirming / newer evidence respecting `as_of` (newer truth that supersedes is a data gap, not a contradiction).
+Compute per-claim survived-confidence: keep `high` only if source_fidelity != contradicted AND >=2/3 verifiers confirm; force DISPUTED on any contradiction; force UNVERIFIABLE if >=2 cannot_confirm/unreachable. Re-dispatch ONLY analysts with remaining `missing_claim_source_ids`, parse failures, or DISPUTED claims, with a stricter prompt; re-`record_visible_packet` (idempotent). Cap at 2 rounds; log residual gaps for the PM to report honestly. Verifiers also obey the leaf-worker rule.
+
+### Stage 3 — Debate pipeline (3 rounds, parallel per round)
+Run the documented rounds, each as a parallel fan-out of `bull_researcher` + `bear_researcher` fed the verified evidence:
+- Round 1: bull writes the long case; bear writes the short case (parallel).
+- Round 2: cross-feed each side the other's round-1 packet for rebuttal (parallel; main thread reads `bull_researcher.json` / `bear_researcher.json` and pastes into the next prompts).
+- Round 3: each side asks three questions; the other answers (parallel).
+Persist each round via `record_visible_decision(run_id, role, packet)` so `all_agents.md` accumulates the full trace. DISPUTED/UNVERIFIABLE claims may appear in a thesis only with an explicit caveat.
+
+### Stage 4 — Verdict + synthesize
+Run one `portfolio_manager` `Task` fed the verified evidence plus all three debate rounds. Record it via `record_visible_decision(run_id, 'portfolio_manager', packet)`, which writes `decision.json` + `final_report.md` and marks the run complete. Then return the complete report inline (SKILL step 5) in the user's language, including the Analyst Work Log, Bull/Bear Debate record, the verification ledger (per material claim: self-confidence, verifier tally, source-fidelity, survived-confidence), all mandated sections, data gaps, short/medium/long-term views, and the `<task>:<source_id>` source table. Link artifacts only in an appendix.
+
+Honest limits: Task fan-out is best-effort, not a guaranteed workflow engine; enforce the barrier by polling artifacts, not by assuming. WebSearch/WebFetch is the only evidence channel (no financial API), so some numeric claims stay "narratively corroborated, not vendor-verified". This is the same auditable contract as the other paths — a stronger runner, not a different audit story.
+
+
+## Agent Output Contract
+
+Evidence agents return:
+
+```json
+{
+  "task": "market_data",
+  "symbol": "NOK",
+  "as_of": "YYYY-MM-DD",
+  "summary": "string",
+  "claims": [{"claim": "string", "evidence": "string", "confidence": "high|medium|low", "source_ids": ["S1"]}],
+  "metrics": {},
+  "sources": [{"id": "S1", "title": "string", "url": "string", "published_at": "YYYY-MM-DD or unknown", "retrieved_at": "YYYY-MM-DD"}],
+  "open_questions": ["string"],
+  "confidence": "high|medium|low"
+}
+```
+
+Debate agents return:
+
+```json
+{
+  "role": "bull_researcher",
+  "symbol": "NOK",
+  "as_of": "YYYY-MM-DD",
+  "verdict": "string",
+  "rating": "Buy|Overweight|Hold|Underweight|Sell",
+  "winner": "bull|bear|balanced|unknown",
+  "summary": "string",
+  "long_thesis": ["string"],
+  "short_thesis": ["string"],
+  "valuation_range": "string",
+  "catalysts": ["string"],
+  "risks": ["string"],
+  "position": "string",
+  "invalidation": ["string"],
+  "source_ids": ["S1"],
+  "confidence": "high|medium|low",
+  "report_markdown": "string"
+}
+```
+
+## Boundaries
+
+- Public-equity-investing and investment-banking methodology is **bundled as local skills**
+  (`skills/public-equity-investing`, `skills/investment-banking`); use them as the research method on
+  BOTH editions. On Codex you may additionally use the curated remote `@public-equity-investing` /
+  `@investment-banking` workflows; on Claude Code (or when the remote workflows are unavailable) the
+  bundled local skills ARE the method, driven by `WebSearch` + `WebFetch`. Treat them as agent
+  playbooks run by subagents, not Python libraries.
+- Keep non-public information out of scope unless the user provides the document directly.
+- For exact index / index-futures (incl. night session) / FX / rates / vol / commodity / stock levels, call the **`get_quote`** MCP tool (keyless, ~15m delayed; accepts names like `KOSPI`/`纳指期货`/`VIX`/`美元指数` or raw tickers) and cite it. Web search is the interpretation layer and the fallback when `get_quote` errors — then record the gap in `open_questions`. `get_quote` is delayed market data, never a real-time feed.
+- Every material claim should map back to an evidence packet with sources and confidence.
+- Evidence sources are globally scoped as `<task>:<local_source_id>` and mirrored in `source_manifest.json`; never cite bare `S1/S2` after packets are merged.
+- Final manager reports must include separate visible sections for market expectations / implied beat-miss thresholds, analyst rating or target-price revisions, earnings-call management signals, quant factor / technical risk view, news and management/industry voice signals, short interest / borrow / options where available, strategic transaction or banking-event terms where relevant, data gaps / unavailable data, and separate short-term 1-4 weeks / medium-term 3-6 months / long-term 12 months views. Do not hide these only in the source table. If a data source is unavailable, state that explicitly instead of omitting the section. If no key source is missing, include a data-gaps section saying no critical gaps were found.
+- Final manager reports must also include an "Analyst Work Log" / "分析师工作记录" section summarizing every evidence agent packet, plus a "Bull/Bear Debate" / "多空辩论记录" section summarizing the long case, short case, rebuttal, unanswered questions, and who won. Do not replace these with a one-paragraph execution summary.
+- Completed runs must write `final_report.md`, `user_response.md`, `artifact_index.md`, `report_quality.json`, one Markdown file per evidence analyst, and Markdown files for `bull_researcher`, `bear_researcher`, and `portfolio_manager`. If `report_quality.json` is not `passed`, report the run as `needs_revision`, not complete.
+- The `management_industry_voices` agent only uses publicly verifiable commentary from executives, board members, official company channels, customers, suppliers, competitors, regulators, industry experts, and channel voices. It must separate direct quotes, paraphrases, and media interpretation, and must not imply non-public inside information.
+- Fail closed on visibility: if visible agent/thread tools are unavailable, say that visible subagents are unavailable in this runtime and use MCP only with that limitation stated.
+- Never let a subagent call `@alphacouncil-agent`, `collect_evidence`, `analyze_symbol`, or `read_run`; visible agents are leaf workers.

package/skills/investment-banking/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: investment-banking
+description: Local, edition-agnostic investment-banking / event-analysis methodology playbook for AlphaCouncil's ib_event_analysis role (and any M&A, ECM, debt, buyback, or strategic-transaction question). On Codex this replaces or supplements the curated remote @investment-banking workflow; on Claude Code it IS the workflow (driven by WebSearch + WebFetch). No financial-data API or vendor key required.
+---
+
+# Investment Banking — Event Analysis (bundled playbook)
+
+This skill lets AlphaCouncil analyze corporate transactions and banking events **without** depending on
+Codex's curated remote `@investment-banking` plugin. Runnable method with gates, evidence via
+`WebSearch` + `WebFetch`.
+
+> Educational/research only. Not investment advice, not a solicitation. Report missing data honestly.
+
+## When to use
+
+For the `ib_event_analysis` role, or whenever the request involves a deal/transaction: M&A, equity
+issuance (ECM/secondary/ATM), debt issuance/refinancing, buyback/dividend, spin-off/divestiture, or a
+strategic transaction (e.g. major supply/partnership terms). Return the standard evidence packet; keep
+JSON field names in English, prose in the user's language.
+
+## Deal taxonomy → what to extract
+
+- **M&A** — acquirer/target, consideration (cash/stock/mix), price + premium to unaffected, structure,
+  financing, expected synergies, accretion/dilution, conditions, regulatory/antitrust path, break fee,
+  expected close.
+- **ECM** — offering size, type (primary/secondary/ATM/convertible), price/discount, dilution %, use of
+  proceeds, lockups, underwriters.
+- **Debt** — size, tenor, coupon/spread, secured/unsecured, use of proceeds (refi vs growth), covenant
+  and maturity-wall impact, rating action.
+- **Buyback / dividend** — authorization size vs market cap, pace, funding source, signal vs dilution
+  offset, capital-allocation tradeoff.
+- **Spin-off / divestiture** — perimeter, rationale, stranded costs, pro-forma leverage, tax treatment.
+- **Strategic transaction** — counterparty, scope, exclusivity, financial terms where disclosed, the
+  earnings/strategic impact.
+
+## Sourcing ladder (per claim, in order)
+
+1. **Primary filing/release first**: the 8-K and its exhibits, 424B / S-4 / proxy (DEFM14A), the deal
+   press release on the issuer IR domain, and the rating-agency release. Non-US → the local
+   exchange/regulator filing.
+2. Dated, scoped search (issuer IR + `sec.gov` + the named counterparty), then one disconfirming query
+   (`<deal> regulatory block` / `antitrust` / `financing risk` / `terminated`).
+3. **WebFetch the actual document**; quote exact terms (price, premium, size, coupon, close date) with
+   dates.
+4. Corroborate headline terms across the filing AND a second independent source; single-source → `medium`.
+5. Paywalled/unconfirmed/rumored → `open_questions`; clearly label rumor vs confirmed.
+
+## Analysis to produce
+
+- **Terms table** — the hard numbers (price, premium, size, %, dates) each mapped to a `source_id`.
+- **Impact** — accretion/dilution, pro-forma leverage/coverage, EPS and capital-structure effect.
+- **Risk path** — regulatory/antitrust, financing, shareholder-vote, MAC/closing conditions, timeline.
+- **Read-through** — what the deal implies for the thesis (catalyst or invalidation), feeding the
+  bull/bear debate and the portfolio-manager verdict.
+
+## Gates (must pass before the packet is "done")
+
+1. **Primary-document gate** — headline terms come from the filing/release, not a paraphrase; each has a
+   real `url` + `published_at`.
+2. **Confirmed-vs-rumor gate** — anything not in a filing/official release is labeled rumor and
+   confidence-capped.
+3. **Quantify gate** — premium, dilution %, leverage delta, and close date are stated as numbers or
+   explicitly listed as unavailable in `open_questions`.
+4. **Honesty gate** — no invented terms; unknowns are surfaced, not guessed.
+
+## Anti-rationalizations
+
+- "The press summarized it" → fetch the actual 8-K/424B and quote exact terms.
+- "Premium is roughly X" → compute it from the disclosed price vs the unaffected price, with both dates.
+- "It'll obviously clear regulators" → state the actual approval path and the real risk, or mark unknown.

package/skills/public-equity-investing/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: public-equity-investing
+description: Local, edition-agnostic equity-research methodology playbook for AlphaCouncil analysts. Use as the research method for the evidence roles (market_data, earnings_deep_dive, forward_expectations, sell_side_revisions, earnings_call_transcript, quant_factor, valuation_long_short, news_industry_management, management_industry_voices, insider_sec). On Codex this replaces or supplements the curated remote @public-equity-investing workflow; on Claude Code it IS the workflow (driven by WebSearch + WebFetch). No financial-data API or vendor key required.
+---
+
+# Public Equity Investing (bundled playbook)
+
+This skill gives every AlphaCouncil analyst the same deep-research method **without** depending on
+Codex's curated remote `@public-equity-investing` plugin. It is a runnable method with gates, not a
+style guide. Evidence is gathered live via the agent's own web search (`WebSearch` + `WebFetch`).
+
+> Educational/research only. Not investment advice. Report missing data; never fabricate figures.
+
+## When to use
+
+Whenever an AlphaCouncil evidence analyst runs. Each analyst applies the **sourcing ladder** and its
+**role focus** below, then returns the standard JSON evidence packet (see AlphaCouncil's Agent Output
+Contract). Keep JSON field names in English; write prose in the user's language.
+
+## Sourcing ladder (per claim, in order)
+
+1. **Primary document first.** Prefer the issuer/regulator over aggregators:
+   - filings → SEC EDGAR full-text (`sec.gov`), 10-K/10-Q/8-K, 424B, Form 4; non-US → the local
+     regulator / exchange filing (HKEX, SEHK, EDINET, etc.).
+   - earnings → the 8-K Ex-99.1 press release and the IR deck / transcript on the company IR domain.
+   - price/quote → the exchange or a named quote page, with the exact as-of timestamp.
+2. **Dated, scoped search.** Run a primary-locator query (restrict to `sec.gov` + the company IR/exchange
+   domain), then a recency query (`<ticker> <topic> <year>`), then ONE mandatory disconfirming query
+   (`<ticker> guidance cut` / `downgrade` / `accounting concern` / `short thesis`).
+3. **WebFetch the actual page** and quote exact numbers with their real dates (signal date, source
+   publication date, retrieval date are distinct).
+4. **Corroborate** any market-moving number across at least two independent sources; if only one exists,
+   mark confidence `medium` and say so.
+5. **Anything paywalled / stale / unfetchable → `open_questions`.** Do not invent it.
+
+## Role focus
+
+- `market_data` — price action, liquidity/volume, range vs 20/50/200-day, relative strength vs index/peers.
+- `earnings_deep_dive` — last reported quarter: revenue/margins/segments, surprises vs consensus, guidance.
+- `forward_expectations` — consensus estimates, implied beat/miss thresholds, what's priced in.
+- `sell_side_revisions` — rating and target-price changes (who, when, from→to), dispersion of targets.
+- `earnings_call_transcript` — management tone, commitments, hedges, repeated themes, Q&A pressure points.
+- `quant_factor` — momentum, trend, volatility, volume/liquidity, relative strength, short interest,
+  borrow, options IV/skew/expected move when available.
+- `valuation_long_short` — see Valuation frameworks below; produce a long thesis AND a short thesis.
+- `news_industry_management` — recent catalysts, industry context, regulatory/competitive backdrop.
+- `management_industry_voices` — publicly verifiable commentary only; separate direct quote vs paraphrase
+  vs media interpretation; never imply non-public information.
+- `insider_sec` — Form 4 insider transactions, buybacks, dilution, debt, capital allocation.
+
+## Valuation frameworks (valuation_long_short)
+
+Use at least two, and state assumptions explicitly:
+
+- **Comparables** — peer EV/EBITDA, P/E, P/S, EV/Sales with the peer set named and dated.
+- **DCF / reverse-DCF** — what growth + margin the current price already implies; is it achievable?
+- **Scenario** — bear / base / bull price targets with the trigger for each.
+- **Catalyst & invalidation** — name the events that confirm or break the thesis.
+
+Output a `valuation_range` plus the long thesis and short thesis; map every number to a `source_id`.
+
+## Gates (must pass before a packet is "done")
+
+1. **Primary-source gate** — every material claim cites a real `url` with a `published_at`; no bare
+   aggregator paraphrase for a market-moving number.
+2. **Disconfirming gate** — you ran at least one query designed to break the thesis.
+3. **Recency gate** — figures carry real dates; stale data is flagged, not presented as current.
+4. **Honesty gate** — missing/unavailable data is listed in `open_questions`; confidence reflects it.
+
+## Anti-rationalizations
+
+- "I already know this stock" → markets move; re-fetch dated primaries anyway.
+- "One source is enough" → corroborate market-moving numbers or mark `medium`.
+- "Close enough" → quote the exact figure and date, or route to `open_questions`.