alphacouncil-agent 0.5.0

package/.opencode/agent/alphacouncil-social_pulse.md

@@ -0,0 +1,54 @@
+---
+description: "Retail Sentiment and Crowding Analyst for AlphaCouncil equity research. sentiment, crowding, social"
+mode: subagent
+model: anthropic/claude-haiku-4-5-20251001
+temperature: 0.1
+permission:
+  edit: deny
+  bash: deny
+  webfetch: deny
+  websearch: allow
+---
+
+<!-- GENERATED by scripts/sync-personas.mjs from personas/. Do not edit. -->
+
+You cover a dimension no other seat does: **how crowded this trade is, and where the circulating story differs from the filed facts.**
+
+## Accept this seat's boundary first, or your output does harm
+
+Call `get_social_pulse`. You get Reddit (searched inside the equity subreddits, not site-wide), Hacker News, and whichever Bluesky handles the user configured.
+
+**X / Twitter is not in there, and that is not a configuration problem.** As of 2026-07 there is no free discovery channel for X: Nitter search is dead on every surviving instance, the X API bills per post retrieved, xAI's x_search bills per call, StockTwits sits behind Cloudflare, and Bluesky's search requires authentication.
+
+That means **professional FinTwit is not covered**, and that layer is precisely where the most valuable equity discussion happens. **Reddit is not a substitute for it.** State this blind spot in open_questions plainly -- do not soften it, and never imply you have seen the whole social picture.
+
+## What you produce
+
+1. **Crowding, not a sentiment score**
+Do not score sentiment. Averaging a pile of retail posts yields the average of the noise. Produce instead:
+- The **change in mention frequency** against an earlier window. A jump in frequency is itself a signal, independent of direction.
+- The **shape of the consensus**: is the discussion one-sided or contested? One-sided optimism is crowding, and so is one-sided pessimism -- opposite directions, both risks.
+- Cross-reference the put/call open-interest ratio from `get_options_chain`. Options positioning is far more reliable than post sentiment.
+
+2. **The gap between the story and the facts -- this seat's most valuable output**
+Take each circulating claim and hold it against the filed facts in the evidence chain:
+- Is there a widely believed claim the filings do not support? **This is the most valuable finding**, because it gives you the direction of the crowding and the path to falsify it at the same time.
+- Is there a fact stated plainly in the filings that nobody in the discussion mentions? An ignored fact is often an unpriced one.
+
+3. **What Hacker News is specifically for**
+HN is nearly useless on financials and occasionally very strong on **whether a technical claim is real** -- the comments routinely contain people who build the thing being discussed, correcting the article. Where the thesis depends on a technical judgment (process node, yield, architecture, performance), the comment thread is worth reading on its own.
+
+4. **A quoted X post must be verified**
+If a news item or search result quotes an X post, confirm it with `verify_x_post`. **A decoded timestamp proves nothing** -- any invented nineteen-digit id decodes to a plausible date. Existence has to be checked separately.
+
+## Hard rules
+
+- **Nothing from this layer may enter the conclusion on its own.** It can only be a lead to verify or a counter-argument, and it enters the factual basis only once a filing or a dated source confirms it. There is no exception to this.
+- **Mention volume measures attention, not correctness**, and the most-engaged posts are the most emotional ones. Do not rank by engagement and read the top as representative.
+- **Reddit search matches post bodies too**, so a result whose title lacks the term is normal. Each result carries `matched_in`; open the link before citing anything marked as matching in the body.
+- **Where an engagement count is unavailable, write unknown. Never estimate it.**
+- Search adversarially: having read the bullish discussion, run a bearish pass. You find what you search for, and that is an echo chamber rather than evidence.
+
+## Output
+
+An evidence_packet. `claims` in three kinds: (1) crowding observations -- frequency, shape of consensus, options cross-reference; (2) the gap between story and filed fact; (3) community scrutiny of a technical claim, where applicable. `open_questions` **must** include the X / FinTwit blind spot.

package/.opencode/agent/alphacouncil-valuation_long_short.md

@@ -0,0 +1,50 @@
+---
+description: "Valuation & Long/Short Analyst for AlphaCouncil equity research. valuation, thesis, position-sizing"
+mode: subagent
+model: anthropic/claude-sonnet-4-5
+temperature: 0.1
+permission:
+  edit: deny
+  bash: deny
+  webfetch: allow
+  websearch: allow
+---
+
+<!-- GENERATED by scripts/sync-personas.mjs from personas/. Do not edit. -->
+
+Your job is to translate the business into a price range and say which assumptions that range depends on.
+
+## What you produce
+
+1. **Choose the right method first; the wrong one invalidates everything after**
+- Stable, predictable earnings: DCF or an owner-earnings multiple.
+- Cyclical: **use mid-cycle earnings**, never the current print. A low multiple on peak earnings is a trap.
+- High growth, unprofitable: unit economics plus an endgame share, with the endgame assumption written out.
+- Asset-heavy or distressed: liquidation value and replacement cost.
+State which you chose and why.
+
+2. **Three scenarios, each with explicit assumptions**
+
+| Scenario | Key assumptions (growth / margin / terminal multiple) | Value per share | Implied return |
+
+- The scenarios must differ **in their assumptions**, not by flexing a midpoint 20% either way. The latter is fake scenario analysis.
+- Label each assumption's origin: from a filing, from guidance, or derived by you. Derived ones must show the derivation.
+
+3. **Back out what the market currently assumes**
+Worth more than the forward valuation: **what growth rate and margin does the current price imply?** Compute it, then say whether that implied set is aggressive, reasonable or conservative.
+
+The disagreement always lives here -- not in what your model outputs, but in where your view of the same assumptions differs from the market's.
+
+4. **Comparable multiples**
+List comparables where they exist, and say **why they are comparable**: same business model? same point in the cycle? same capital structure? If comparability cannot be argued, omit them -- a wrong comp set is worse than none.
+
+## Hard rules
+
+- **Every assumption must be falsifiable**, written as "if X reaches Z by Y".
+- **Never output a point estimate.** A single target price implies precision that does not exist. Give a range and the basis for its width.
+- **State which assumption the valuation is most sensitive to**: a 10% move in which variable moves value by how much.
+- Where the data cannot support a valuation, write "no defensible range can be built" and name what is missing. **Do not assemble a number out of comparable multiples to fill the gap.**
+
+## Your most common error
+
+**Reaching the conclusion before building the model.** A valuation model has enough degrees of freedom to justify any target. There is one defence: **fix the assumptions and their sources first, then compute**, never the reverse.

package/AGENTS.md

@@ -0,0 +1,96 @@
+# Agent Instructions
+
+Read `CLAUDE.md` first. It defines the workflow, analyst roles, final-report requirements, evidence contract and repository boundaries.
+
+For report-generation behavior, also follow `docs/report-contract.md`. The chat handoff may be concise, but the saved report and artifact files must preserve the full evidence chain.
+
+For anti-laziness governance, also follow `skills/agent-skills-governance/SKILL.md`. It is bundled with the plugin so installed agents inherit the same gates without separately installing `addyosmani/agent-skills`.
+
+Run `npm run check` after any code or prompt change.
+
+## Hosts
+
+The MCP server is the load-bearing integration on every host: it reads `personas/` directly,
+so a host that ignores the generated agent files still gets correct prompts.
+
+| Host | Config | Agents | Skills |
+|---|---|---|---|
+| Claude Code | `.claude-plugin/plugin.json`, `.mcp.json` | `.claude/agents/alphacouncil-*.md` | `skills/` via the plugin manifest |
+| Codex | `.codex-plugin/plugin.json`, `.mcp.json` | — | `skills/` via the plugin manifest |
+| OpenCode | `opencode.json` | `.opencode/agent/alphacouncil-*.md` | see the caveat below |
+| Grok Build | `.grok/config.toml` | `.grok/agents/alphacouncil-*.md` | `AGENTS.md` (this file) |
+
+### OpenCode
+
+Verified against a real opencode 1.18.4 install rather than from documentation:
+
+- `opencode mcp list` shows `alphacouncil-agent connected`. The MCP entry must use
+  OpenCode's shape — `{"type":"local","command":["node","./mcp/server.mjs"]}` — a single
+  argv array. Copying Claude Code's `{command, args}` produces a server that never starts,
+  and the env key is `environment`, not `env`.
+- `opencode debug agent alphacouncil-<role>` parses the generated agent files, resolves
+  `anthropic/claude-…` into a provider and model, and applies their permissions.
+  OpenCode does **not** read `.claude/agents/`, `.mcp.json` or `.claude/settings.json`.
+- `opencode.json` deliberately declares **no** global `permission` block. A global block is
+  merged into every agent and overrides the per-agent one, which silently hands the debate
+  roles the network access they are specifically denied. Verified both ways: with the block,
+  `bull_researcher` resolved to `websearch: allow`; without it, `deny`.
+- Per-agent permissions come from each persona's `tools_hint`, so only the roles that
+  actually gather evidence get the network, and no role can edit files or run shell commands.
+
+**Skills:** opencode 1.18.4 serves `debug skill` from a static catalogue -- a skill added
+at runtime never appears, in any location, including `~/.claude/skills` and with a clean
+`OPENCODE_CONFIG_DIR`. Tested both with and without third-party plugins. So the workflow
+does not ship as skills on OpenCode; it ships through `instructions`, which IS resolved:
+`opencode debug config` shows all four workflow files loaded alongside `AGENTS.md`. The
+MCP tools and `.opencode/agent/*.md` carry the rest.
+
+`websearch` is gated in OpenCode — it needs the OpenCode provider or `OPENCODE_ENABLE_EXA=1`.
+Run `preflight_permissions` before a fan-out; it reads OpenCode's permission syntax too.
+
+### Grok Build
+
+Verified against a real install (grok 0.2.101) rather than from documentation:
+
+- MCP lives in `.grok/config.toml` as TOML, not JSON:
+  `[mcp_servers.alphacouncil-agent]` with `command`, `args` and `enabled`. Generate it with
+  `grok mcp add alphacouncil-agent -s project -t stdio node -- ./mcp/server.mjs` rather than
+  hand-writing it. Grok also lists `.mcp.json` among its config sources, so the Claude Code
+  file is read too.
+- **A repo-local server will not start until the folder is trusted.** `grok mcp doctor`
+  reports `folder untrusted (repo-local (project-scoped) server not started)`. That is a
+  security prompt, not a misconfiguration: trust the folder on first launch.
+- `AGENTS.md` is the project system prompt, which is why the generated agents set
+  `agents_md: true` and inherit it.
+- Agent definitions are `.md` with `name` / `description` frontmatter in `.grok/agents/`.
+  Every generated seat uses `permission_mode: plan`, matching the bundled read-only
+  `explore` agent: the council gathers and reasons, it never edits the repo.
+- Skills resolve from `.grok/skills/` and `.claude/skills/`. This repo ships neither, so on
+  Grok Build the workflow arrives through `AGENTS.md` plus the MCP tools, the same shape
+  that works on OpenCode.
+
+## Market data coverage
+
+Structured financials come from each market's own regulator, and the pipeline degrades in
+a stated order rather than quietly becoming US-only.
+
+| Market | Regulator | Key needed | What you get |
+|---|---|---|---|
+| US | SEC EDGAR | none | Full XBRL history with filing dates |
+| Taiwan | TWSE OpenAPI | none | Quarterly income-statement summary |
+| Korea | DART | `ALPHACOUNCIL_DART_KEY` | Full statements |
+| Japan | EDINET v2 | `ALPHACOUNCIL_EDINET_KEY` | Filing index; documents are XBRL in a ZIP |
+| Hong Kong, China A | HKEXnews, cninfo | n/a | No machine-readable API; PDFs only |
+
+Both keys are free. Register at <https://opendart.fss.or.kr> and at the EDINET portal,
+then export them. Nothing breaks without them: `market_coverage` reports which symbols
+have no feed, and the grounding block tells analysts that any financial figure for those
+names must come from a primary document they actually read and be cited as such.
+
+Korea indexes by DART's 8-digit `corp_code`, which is not the ticker -- Samsung
+Electronics is `00126380`, SK hynix `00164779`. Japan uses a 5-digit `secCode`, so
+`285A.T` becomes `285A0`.
+
+Call `market_coverage` before building a report across markets. Without it a memory-industry
+report quietly becomes a Micron report, because Micron is the participant whose numbers
+were easy to fetch.

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+Notable changes per release. Dates are UTC.
+
+## [0.5.0] — 2026-07-26
+
+Everything below is keyless: no API key, no account, no config file.
+
+### Added
+
+- **Options chain** (`get_options_chain`) from CBOE delayed quotes — ATM implied-volatility
+  term structure, 25-delta skew, put/call ratios on open interest and volume, the strikes
+  holding the most open interest, and the ATM spread as a share of mid.
+- **News layer** (`get_news`) over Yahoo Finance RSS, Google News RSS and SEC EDGAR Atom,
+  with a recency gate that excludes undated and out-of-window items rather than showing
+  them as recent.
+- **Market narrative** (`get_market_narrative`) — what the market is currently talking
+  about, ranked by share of coverage, with each theme paired against the market series that
+  would corroborate it. A theme leading coverage while its series has not moved is the
+  finding, not the headline count.
+- **Social layer** (`get_social_pulse`, `verify_x_post`) over Reddit, Hacker News and
+  Bluesky, plus single-post verification against an X post id.
+- **Options bench**: Taleb, Natenberg and Sinclair, and **Michael Burry** on the
+  adversarial roster. The bench is now 21 lenses across six rosters.
+- **Price bands are a mandatory report section.** Every seat contributes the price question
+  its own method implies — Graham's calculable floor, Marks' do-not-touch level, Thorp's
+  price at which expected value turns positive, the short seller's cover level and carry.
+- `market_narrative` and `social_pulse` analyst seats, on the `full` roster. The default
+  fan-out stays at eight.
+
+### Changed
+
+- **Masters now receive the established facts directly**, not only the analysts' packets,
+  with the packets relabelled as other seats' readings. Previously all 21 lenses saw the
+  world through one selection of what mattered, so a weak packet biased every seat
+  identically.
+- All 21 masters state how they think, what they notice first, their characteristic
+  challenge, and their own failure mode.
+- The ten stub personas — `bull_researcher` was 79 characters — are rewritten around what
+  each seat is for and how it characteristically fails.
+- Verifiers gained a claim-selection rule (verification runs on a budget), their own failure
+  modes, and knowledge of which claims this system cannot settle at all.
+- `screen_ticker` accepts a `ticker` and resolves the CIK itself; `cik` is no longer required.
+- **The master bench and the verifier pass now run on every host.** They were described only
+  in the Claude Code section of `SKILL.md`, so on Codex and OpenCode the twenty-one lenses
+  and three verifiers never executed at all — the same plugin was a materially different
+  product depending on where it ran.
+- **`list_council_options` and a mandatory Stage 0.** A council is 7 to 44 seats, which is
+  the user's time and money, so the host asks which one to run instead of choosing silently
+  — and is told when not to ask, because a confirmation nobody needed is an interruption.
+- **Grok Build support**, verified against grok 0.2.101: `.grok/config.toml` (TOML, not
+  JSON), 14 generated `.grok/agents` definitions, and `AGENTS.md` as the project prompt. A
+  repo-local server stays unstarted until the folder is trusted, which is a security prompt
+  rather than a misconfiguration.
+- `plan_visible_run` gathers the established facts itself. It previously accepted them only
+  if the caller passed them and nothing told the caller to, so on the visible path — the one
+  Claude Code uses — every analyst and every master ran with no filings, no quote and no
+  macro, and nothing in the output said so.
+- A run that selects a master bench and records no opinions is now `incomplete`, and the
+  banner names the seats that never reported.
+
+### Fixed
+
+- **The npm package shipped no host agent files.** `.claude/agents/`, `.opencode/agent/` and
+  `.grok/agents/` were all outside `files`, so an install gave you the server and no
+  subagent definitions for three of the four hosts.
+- **`CLAUDE.md` listed three roles that no longer exist** — `sell_side_revisions`,
+  `earnings_call_transcript` and `management_industry_voices` — and it is loaded as an
+  instruction file, so an agent reading it would dispatch seats that had been merged away.
+- Bilingual `{en, zh}` labels rendered as `[object Object]` next to real numbers, which reads
+  as a broken field rather than a missing one. A contract test now renders every surface in
+  both languages against object-label fixtures.
+- `SKILL.md` named none of the data tools, including `screen_ticker`. It is the runtime
+  instruction Codex, OpenCode and Grok Build load, so a tool it never names is a tool those
+  hosts never call. Nothing failed; the capability was invisible.
+
+- `screen_ticker` offered a `ticker` property in its schema and threw on anything without a
+  `cik`, so a caller passing the documented argument got an error.
+- `get_options_chain` read its headline IV and skew from the nearest expiry, which can be
+  one day out. A 1-DTE ATM prices pin risk rather than volatility: on a live chain it
+  printed 69.6% between neighbours at 98.7% and 105.2%. Both now read from the first expiry
+  at least a week out.
+- Contracts reporting `iv = 0` are excluded from the term structure. CBOE returns zero for
+  expired and deep-in-the-money contracts, and a zero entering an IV mean does not look like
+  a gap — it looks like a calm stock.
+- A site-wide Reddit search for a ticker name returned unrelated posts; search is now
+  restricted to the equity subreddits.
+- Hacker News search matched "Micron" against "microkernels" and "Microsoft" through
+  Algolia's typo tolerance, which is now disabled with the phrase quoted.
+- Restoring the analyst bodies dropped content from three merged roles (earnings call,
+  sell-side revisions, industry voices). All three are restored, and the test that guards
+  the merge now requires each absorbing seat to both declare what it absorbed and carry the
+  topic, rather than matching one literal phrase.
+
+## [0.4.0] — 2026-06-23
+
+Keyless real market data (`get_quote`).
+
+## [0.3.2] — 2026-06-22
+## [0.3.1] — 2026-06-22
+
+Bundles `agent-skills-governance`, an anti-laziness skill with explicit stop gates.
+
+## [0.3.0] — 2026-06-22
+
+The shared server runs the three-round debate, enforces the missing-source, full-run and
+report-quality gates, writes concise and full report artifacts, and supports native Windows
+Codex CLI launching.
+
+## [0.2.0] — 2026-06-22
+
+Full-council enforcement, three-round debate, verification gate.

package/CLAUDE.md

@@ -0,0 +1,144 @@
+# Claude Instructions For This Repository
+
+You are working on `alphacouncil-agent`, a Codex plugin for public-equity research.
+
+## Purpose
+
+The plugin turns `@alphacouncil-agent <ticker/request>` into a full equity-research workflow:
+
+1. Spawn or plan specialized analyst workers.
+2. Produce JSON evidence packets with sourced claims.
+3. Merge packets into a shared evidence base.
+4. Run bull and bear researchers.
+5. Run a portfolio manager to decide Buy / Overweight / Hold / Underweight / Sell.
+6. Write a complete final report directly in chat and to `~/.alphacouncil-agent/runs/<run_id>/final_report.md`.
+
+Default behavior is full workflow. Do not downgrade to lite, smoke-test, or debug output unless the user explicitly asks for it.
+
+## Agent-Skills Governance
+
+Also follow `skills/agent-skills-governance/SKILL.md`. It is bundled with this plugin and applies the `addyosmani/agent-skills` style of explicit gates, anti-rationalizations, and exit criteria to AlphaCouncil runs. Do not treat it as an optional local setup step.
+
+## Analyst Roles
+
+Default evidence roles (the eight-seat default fan-out):
+
+- `market_data`
+- `earnings_deep_dive` — absorbed the former standalone earnings-call role
+- `forward_expectations` — absorbed the former standalone sell-side-revisions role
+- `quant_factor`
+- `valuation_long_short`
+- `news_industry_management` — absorbed the former standalone industry-voices role
+- `insider_sec`
+- `ib_event_analysis`
+
+Optional analysts, on the `full` roster rather than the default:
+
+- `macro_regime`
+- `market_narrative`
+- `social_pulse`
+
+Master bench: 21 lenses across six rosters, run between evidence and debate on **every**
+host. Verifiers: `source_fidelity`, `rederivation`, `refuter`. See `skills/alphacouncil-agent/SKILL.md`
+for the workflow and `docs/personas.md` for the full roster.
+
+Debate roles:
+
+- `bull_researcher`
+- `bear_researcher`
+- `portfolio_manager`
+
+## Hard Output Rules
+
+Also follow `docs/report-contract.md`.
+
+Final reports must include:
+
+- conclusion and final rating
+- analyst work log summarizing every evidence agent
+- bull/bear debate record
+- long thesis
+- short thesis
+- market expectations and implied thresholds
+- analyst rating and target-price revisions
+- earnings-call management signals
+- quant factor / technical risk view
+- news and management/industry voice signals
+- short interest / borrow / options information when available
+- strategic transaction or banking-event analysis when relevant
+- valuation range
+- catalysts
+- risks
+- position recommendation
+- short-term 1-4 week view
+- medium-term 3-6 month view
+- long-term 12 month view
+- data gaps / unavailable data
+- invalidation conditions
+- confidence
+- source table
+
+The final chat handoff may be concise, but it must not replace the saved report. 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, bear, and portfolio manager. Tell the user where those files are.
+
+Never hide missing data. If a source is unavailable, say so in `open_questions` and in the final report's data-gap section. If no critical data is missing, explicitly state that no critical data gaps were found.
+
+Do not put execution labels like "visible version", "lite", "smoke test", "debug", or "did not use PDF/Data Analytics" in the user-facing investment report.
+
+## Evidence Rules
+
+Every material claim should map to a source ID. Source IDs must be globally scoped as:
+
+```text
+<task>:<local_source_id>
+```
+
+Example:
+
+```text
+market_data:S1
+earnings_deep_dive:S3
+quant_factor:S2
+```
+
+Do not cite bare `S1` after packets are merged.
+
+## Runtime Files
+
+Generated files live under:
+
+```text
+~/.alphacouncil-agent/runs/<run_id>/
+```
+
+Typical outputs:
+
+- `status.json`
+- `events.jsonl`
+- `evidence.json`
+- `<task>.json`
+- `source_manifest.json`
+- `bull_researcher.json`
+- `bear_researcher.json`
+- `manager_synthesis.json`
+- `decision.json`
+- `final_report.md`
+- `all_agents.md`
+
+Do not commit generated run artifacts.
+
+## Development Rules
+
+- Keep the implementation small.
+- Do not add dependencies unless there is no simple Node.js standard-library path.
+- Preserve the JSON packet contracts in `mcp/server.mjs`.
+- After changes, run:
+
+```bash
+npm run check
+```
+
+## Important Boundaries
+
+This repository is an independent Codex plugin implementation. It can be inspired by multi-agent investment-committee workflows, but do not copy external project source code into this repository.
+
+Public Equity Investing and Investment Banking are Codex skills or remote workflows, not importable JavaScript libraries. Treat them as agent instructions, not as packages to `import`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhao73
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.