tradingcodex 0.1.0__py3-none-any.whl

workspace_templates/modules/paper-trading/module.json

@@ -0,0 +1,16 @@
+{
+  "id": "paper-trading",
+  "description": "Experimental simulated portfolio adapter for paper execution without live broker integration.",
+  "requires": {
+    "modules": [
+      "tradingcodex-mcp",
+      "stub-execution"
+    ]
+  },
+  "provides": {
+    "capabilities": [
+      "execution.paper"
+    ]
+  },
+  "conflicts": []
+}

workspace_templates/modules/postmortem/files/.tradingcodex/workflows/postmortem.yaml

@@ -0,0 +1,12 @@
+name: postmortem
+trigger_examples:
+  - rejected_order
+  - executed_paper_order
+  - thesis_change
+  - policy_violation
+  - skill_change_proposal
+
+outputs:
+  directory: trading/reports/postmortem
+  format: json
+  filename_pattern: "*.postmortem_report.json"

workspace_templates/modules/postmortem/module.json

@@ -0,0 +1,16 @@
+{
+  "id": "postmortem",
+  "description": "Workflow metadata for audit-backed investment process review.",
+  "requires": {
+    "modules": [
+      "repo-skills",
+      "audit"
+    ]
+  },
+  "provides": {
+    "capabilities": [
+      "workflow.postmortem"
+    ]
+  },
+  "conflicts": []
+}

workspace_templates/modules/repo-skills/files/.agents/skills/investment-workflow-map/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: investment-workflow-map
+description: "Map investment requests across asset universes into TradingCodex workflow lanes, role teams, source posture, hero artifacts, support files, and conservative readiness labels."
+---
+
+# Investment Workflow Map
+
+Use this skill when the request is an investment workflow. It improves routing and artifact quality; it does not replace fixed role subagents or let the coordinator perform analyst work directly.
+
+Boundary:
+
+- This skill covers universe classification, workflow-type mapping, source/as-of posture, support gaps, hero/support artifact choice, and conservative readiness labels.
+- Final scenario selection, role team, quality gates, blocked actions, fixed-role dispatch details, role briefs, and user-facing decision states are separate workflow steps.
+- Readiness labels from this map are not approvals, permissions, or execution authorization.
+
+Reference basis: this map incorporates institutional public-equity workflow patterns such as issuer tearsheets, idea triage, pre-earnings previews, post-earnings deep dives, catalyst calendars, thesis trackers, long/short pitches, valuation/model work, model audit, financial normalization, position sizing, hedge design, and report QC. Treat public equity as the first fully specified sleeve, not the only TradingCodex investment universe.
+
+## Universe Boundary
+
+TradingCodex can support multiple investment universes through the same safety model:
+
+- Public equities, ADRs, ETFs, indices, and listed options.
+- Public crypto market research and paper/stub workflows when no account access or trading API is exposed.
+- Macro, rates, FX, commodities, and cross-asset overlays as research, thesis, or portfolio-risk inputs.
+- Credit, convertibles, preferreds, and capital-structure signals as supported workflows when a role skill, external read-only source, and policy boundary are explicitly installed; until then, use them only as inputs to the allowed workflow and label handoff gaps.
+- Private markets, funds, tax, legal, and regulated advice are out of scope unless the user installs explicit skills and policies for those domains.
+
+Live execution remains outside the default product regardless of universe. Any executable action must still pass structured artifacts, policy, approval, TradingCodex MCP, and audit.
+
+## Invocation Boundary
+
+Apply this map when the user asks for investment work on a listed issuer, ticker, public security, ETF/index constituent, crypto asset, macro/commodity/rate/FX exposure, portfolio position, hedge, catalyst, thesis, model, or risk decision.
+
+Do not use this map for generic background research, private-company diligence, banking deliverables, legal/tax advice, raw broker access, direct live execution, or unsupported instruments. When the universe is not fully supported by the installed role skills, classify the work as research-only, screen-grade, or blocked rather than pretending the harness can underwrite it.
+
+## Source Posture
+
+Every investment workflow needs an explicit source posture before synthesis:
+
+- Source categories: issuer/company disclosures, regulator/exchange records, transcripts/presentations, macro or instrument data, internal research or user notes, portfolio/models/trackers, market data/estimates, current news, and instrument-specific sources such as borrow, options, liquidity, credit spread, or chain data when relevant.
+- Freeze time: market-sensitive inputs such as price, consensus, estimates, ownership, short interest, borrow, options, index weights, funding rates, yields, spreads, FX, commodity prices, catalyst dates, and portfolio exposures need an as-of or retrieved-at timestamp.
+- Evidence labels: separate reported facts, issuer claims, consensus/provider data, user-provided inputs, derived calculations, analyst assumptions, and PM judgment.
+- Connector honesty: never imply live Bloomberg, FactSet, official regulator/exchange disclosure feeds, Binance account, broker, email, drive, or internal-system access unless that source is actually callable in the current runtime.
+- Missing or stale load-bearing evidence must lower readiness, confidence, sizing/action language, or circulation status.
+
+## Workflow Taxonomy
+
+| Investment request | TradingCodex lane | Minimum useful team | Hero artifact | Readiness rule |
+| --- | --- | --- | --- | --- |
+| Issuer baseline, company tearsheet, public profile | `research_only` | fundamental, news; add valuation when valuation context is requested | issuer baseline or evidence-backed research note | factual baseline only; no recommendation |
+| Idea screen, market map, watchlist triage | `research_only` or `thesis_review` | fundamental, news, valuation, portfolio when fit matters | idea triage report or watchlist board | research-priority status, not final recommendation |
+| Pre-earnings preview | `thesis_review` | fundamental, news, valuation; add portfolio/risk if position action is requested | earnings preview report | freeze expectation bar and label missing consensus/guide/price data |
+| Post-earnings deep dive | `thesis_review` | fundamental, news, valuation; add portfolio/risk if thesis break or sizing is requested | earnings deep-dive report | state what changed versus prior thesis and which sources are still missing |
+| Catalyst calendar or monitoring queue | `thesis_review` | news, fundamental, portfolio when position context exists | catalyst calendar or tracker | confirmed dates, inferred windows, and unscheduled monitor items stay distinct |
+| Thesis tracker update | `thesis_review` or `portfolio_risk_review` | fundamental, news, valuation, portfolio, risk when action changes | append-only thesis tracker or update memo | separate thesis status, security/instrument readiness, and action threshold origin |
+| Long/short pitch, pair idea, trade expression | `thesis_review` then `portfolio_risk_review` | fundamental, news, valuation, portfolio, risk | trade pitch or memo | expression, catalyst, risk/reward, disconfirmers, and implementation gates must be visible |
+| DCF, comps, model, scenario sensitivity | `thesis_review` | valuation; add fundamental for driver evidence and portfolio/risk for action use | valuation report or workbook | current-price implication, model status, and source-backed assumptions must be explicit |
+| Model update, model audit, financial normalization | `thesis_review` support or `harness_administration` if only process/tooling | valuation plus support/QC; add fundamental for source facts | workbook, audit report, or normalization pack | support files do not create an investment conclusion by themselves |
+| Event-driven, macro/economic impact, policy shock | `thesis_review` or `portfolio_risk_review` | news, fundamental or valuation as relevant, risk; add portfolio when position impact matters | event report or impact map | probabilities, timing, and payoffs are assumptions unless source-backed |
+| Technical, trend, liquidity, volatility, or market-structure review | `research_only` or `portfolio_risk_review` | technical, news; add portfolio/risk when action or sizing is requested | technical/setup report | observations are not trade instructions; stale price data lowers readiness |
+| Position sizing, hedge design, integrated risk plan | `portfolio_risk_review` | portfolio, risk; add valuation/news/technical when thesis or market inputs are stale | risk decision report | missing price/liquidity/borrow/options/funding inputs block implementation-ready language |
+| Report/deck QC or circulation review | `harness_administration` or underlying lane | risk or owning role plus QC support | QC issue log or circulation memo | QC never certifies facts it cannot tie out |
+| Unsupported universe or instrument | `blocked_request` or `research_only` | none, or research roles only | limitation memo | no order path; ask for installed workflow/policy or user-provided evidence |
+
+## Hero And Support Artifacts
+
+Choose a user-facing hero artifact first, then keep deterministic support files behind it:
+
+- Research-heavy work: report, dashboard-style memo, thesis update, catalyst calendar, or evidence pack.
+- Model-heavy work: workbook with a first visible cover or decision dashboard.
+- Support work: source indexes, normalized CSVs, run logs, manifests, issue logs, and raw JSON are audit/support files unless the user explicitly asks for them.
+
+If the user explicitly asks for a quick chat answer or no-file output, stay concise but keep source posture, missing evidence, and readiness visible.
+
+## PM Judgment Questions
+
+Use these questions to sharpen the dispatch brief and synthesis without forcing unrequested methods:
+
+- What changed, and does it change the thesis, estimates, valuation support, sizing, hedge, or next catalyst?
+- What is priced in, what is ignored, and where is the variant view?
+- Why now: catalyst path, evidence cadence, or risk window?
+- What breaks first in downside, and what would kill or upgrade the thesis?
+- What action is allowed now: research, watchlist, wait for proof, re-underwrite, portfolio/risk review, draft order intent, approval, execution, or blocked?
+
+## Readiness Labels
+
+Use conservative labels:
+
+- `factual-baseline`: source-backed context only.
+- `screen-grade`: useful for prioritization, but missing load-bearing evidence.
+- `not-decision-ready`: missing current price, source dates, base case, valid probabilities, portfolio context, instrument support, or implementation inputs required for the user's decision.
+- `ready-for-portfolio-risk`: enough research/valuation/market context exists for sizing, fit, or risk review.
+- `ready-for-draft`: portfolio and risk prerequisites exist and the user explicitly asks for a draft order intent.
+- `blocked`: restricted list, secrets, direct broker access, unsupported live execution, unsupported instrument execution, policy-change-plus-execution, or missing required approval path.
+
+These readiness labels inform synthesis; they do not authorize orders, approvals, or execution.
+
+## Dispatch Rules
+
+- Preserve the original user request and explicit constraints in every role brief.
+- Use the minimum useful role team for the workflow; do not summon the full roster by habit.
+- Keep support skills and support artifacts subordinate to the owning investment workflow.
+- Do not turn examples from this map into mandatory metrics, models, indicators, ratios, or source lists unless the user requested them or policy requires them.
+- Apply source/as-of and read-only evidence boundaries before external MCPs, web sources, connectors, or imported skills.
+- After this map, set the final lane, team, artifacts, blocked actions, and synthesis gate.
+- If this map identifies an investment workflow, natural-language auto-routing can activate dispatch. Do not answer directly with investment analysis before role outputs exist.

workspace_templates/modules/repo-skills/files/.agents/skills/investment-workflow-map/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Investment Workflow Map"
+  short_description: "Map investment workflows across universes to TradingCodex lanes"
+  default_prompt: "Use $investment-workflow-map to classify an investment request before dispatch."
+policy:
+  allow_implicit_invocation: true

workspace_templates/modules/repo-skills/files/.agents/skills/manage-optional-skills/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: manage-optional-skills
+description: "Create, update, archive, delete, activate, and validate role-local optional skills for fixed TradingCodex subagents through the shared workspace skill service, CLI, API, or Django web surface while keeping core skills, role identity, MCP allowlists, permission profiles, and guardrails locked."
+---
+
+# Manage Optional Skills
+
+Use this skill when the user asks to customize a fixed subagent with an optional role-local procedure.
+
+Use $skill-creator for concise `SKILL.md` instructions and metadata. Prefer the shared TradingCodex mutation service through `tcx skills optional ...`, API, or Django web actions instead of hand-editing files. Direct edits are allowed only when repairing a broken workspace, and must preserve the same paths and metadata.
+
+Boundary:
+
+- Optional skills are workspace files, not Django DB rows.
+- Django web, API, CLI, and mainagent actions all use the same application service.
+- Do not edit core skill folders when creating optional skills.
+- Do not change role identity, model settings, permission profiles, MCP allowlists, information barriers, approval authority, execution authority, secret access, or live broker posture.
+- Keep optional skills as work style, checklist, output-shape, or evidence-quality procedures inside the target role boundary.
+
+Files:
+
+```text
+.tradingcodex/subagents/skills/<role>/<skill-name>/SKILL.md
+.tradingcodex/subagents/skills/<role>/<skill-name>/agents/openai.yaml
+.tradingcodex/subagents/skills/<role>/<skill-name>/agents/tradingcodex.json
+.codex/agents/<role>.toml
+```
+
+Skill name rules:
+
+- Use lowercase hyphen-case.
+- Keep the name short and specific.
+- Do not reuse a core skill name.
+- Prefer names that describe the procedure, such as `filing-red-flag-review` or `liquidity-checklist`.
+- Keep `name` and `description` in `SKILL.md` frontmatter; the sidecar JSON is lifecycle metadata only.
+
+Create flow:
+
+1. Identify the target fixed subagent role from the user's request.
+2. Choose a new optional skill name.
+3. Use `tcx skills optional create <skill-name> --role <role> ...` or the Django/API equivalent so validation and projection run together.
+4. Ask before changing a draft to active when the rule changes role behavior materially.
+5. Validate the boundary before final response.
+
+Update flow:
+
+1. Read the existing optional skill files and status JSON.
+2. Preserve the skill name unless the user explicitly asks for a rename.
+3. Use `tcx skills optional update <skill-name> --role <role> ...` or the Django/API equivalent.
+4. Confirm the target role TOML still references the skill only when active.
+5. Validate the boundary before final response.
+
+Archive flow:
+
+1. Use `tcx skills optional archive <skill-name> --role <role>` or the Django/API equivalent.
+2. The service removes the active TOML projection while leaving the skill folder.
+3. Do not remove core skills.
+
+Delete flow:
+
+1. Draft or archived optional skills may be hard-deleted.
+2. Deleting an active optional skill archives and reprojects first unless the user explicitly confirms force deletion.
+
+Status JSON shape:
+
+```json
+{
+  "role": "<target-role>",
+  "name": "<skill-name>",
+  "scope": "role",
+  "status": "active",
+  "created_by": "main-agent",
+  "created_at": "<ISO-8601>",
+  "updated_by": "main-agent",
+  "updated_at": "<ISO-8601>"
+}
+```
+
+TOML block shape:
+
+```toml
+[[skills.config]]
+path = "/absolute/path/to/.tradingcodex/subagents/skills/<role>/<skill-name>/SKILL.md"
+enabled = true
+```
+
+New TOML projections must point to `.tradingcodex/subagents/skills/<role>/<skill-name>/SKILL.md`, not `.agents/skills`.
+
+Validation checklist:
+
+- The optional skill stays within the target role's existing responsibility.
+- The skill does not mention approval, execution, order submission, broker access, secrets, or policy changes unless those are already core responsibilities of the target role.
+- The skill does not create new authorities, new tools, new MCP allowlists, or new permission profiles.
+- The skill does not weaken source/as-of honesty, handoff states, information barriers, or no-overlap role boundaries.
+- The sidecar JSON and TOML projection agree.
+- Django status pages can discover and mutate the skill through the shared service.
+
+Final response:
+
+- State the skill name, target role, status, changed files, and validation result.
+- If blocked, explain which boundary blocked the change and leave existing files unchanged.

workspace_templates/modules/repo-skills/files/.agents/skills/manage-optional-skills/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Manage Optional Skills"
+  short_description: "Maintain role-local optional skills"
+  default_prompt: "Use $manage-optional-skills to create, update, archive, or validate a role-local optional skill."
+policy:
+  allow_implicit_invocation: false

workspace_templates/modules/repo-skills/files/.agents/skills/manage-subagents/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: manage-subagents
+description: "Assign, brief, review, and reconcile fixed-role subagents for artifact handoffs, runtime-label discipline, and role-boundary checks."
+---
+
+# Manage Subagents
+
+Use this skill to assign, review, revise, or reconcile fixed-role subagent work after a workflow lane has been selected.
+
+Boundary:
+
+- This skill covers fixed-role subagent mechanics: state/reuse checks, role skill inspection, capacity planning, dispatch schema, compact brief construction, artifact review, conflict handling, and routing-unverified stops.
+- Base instructions own the non-negotiable dispatch gate and role boundaries.
+- Workflow lane, quality floor, and policy requirements arrive as inputs; do not re-derive them inside every brief.
+- Fixed subagent TOML files own standing role identity, model/tool config, MCP allowlists, artifact walls, and always-on prohibitions.
+- Subagent briefs are assignment envelopes: they carry only the current request, constraints, research artifact language, artifact target, material context, and return contract.
+- Do not move role analysis methods into coordinator briefs. The assigned role's developer instructions and skills define method choice unless the user or policy makes a method binding.
+- Handoffs are no-overlap quality contracts. Downstream roles consume accepted upstream artifacts; they do not redo missing predecessor work unless that work belongs to their own role question.
+
+Core rules:
+
+1. Assign only fixed role subagents installed in `.codex/agents/`.
+2. Address each subagent by the exact `.codex/agents/*.toml` `name` value; do not add unsupported alias fields to Codex TOML.
+3. On main-agent session startup, treat `.tradingcodex/mainagent/session-start.json` as a readiness plan. Do not spawn subagents until a natural-language investment request, explicit subagent request, or explicit workflow invocation activates a workflow.
+4. Do not let the coordinator answer investment analysis directly when a fixed role subagent owns the work.
+5. Give each subagent a compact assignment envelope: task, known inputs, expected output path, research artifact language, request-specific out-of-scope items, and a minimal return contract.
+6. Prefer artifact paths over pasted raw context when handing off work.
+7. Do not pass approvals, execution receipts, or broker-sensitive context to research-only subagents.
+8. Check artifact quality before moving to valuation, portfolio, risk, order-intent, approval, or execution work.
+9. Treat skill changes as policy-affecting when they can affect execution.
+10. Use the local CLI wrapper `./tcx`; do not rely on `tcx` being present in PATH.
+11. Use only fields exposed by the active Codex `spawn_agent` schema. Current preferred shape is `spawn_agent(agent_type="<role>", message="TASK: ... DELIVERABLE: ... CONTEXT: ... INSTRUCTIONS: ... RETURN: ...", fork_context=false)` when the schema lists or accepts the fixed role as `agent_type`.
+12. When selecting a fixed `agent_type`, do not use a full-history fork. Pass the compact assignment envelope as the message and set `fork_context=false` as a top-level tool argument when the schema supports it. Do not pass model, reasoning, or service-tier overrides.
+13. Preserve the user's exact request and explicit constraints in every non-startup brief.
+14. Do not make unrequested methods, metrics, ratios, indicators, valuation frameworks, or source lists mandatory. Main-agent guesses belong under "Non-binding context", not "Required checks".
+15. Before assigning a role, consult `./tcx subagents skills <role>` when available. Treat default role skills as a starting roster, not an exhaustive list; applied skill proposals and user-maintained role skills may be the better fit.
+16. Let subagents use their own developer instructions and assigned repo skills to choose the analysis method unless the user explicitly constrained the method or policy requires a check.
+17. Include the universe, workflow type, and readiness/support-gap posture when it materially changes the role brief.
+18. When external data may be used, include compact source/as-of requirements. Do not paste long source-class lists or evidence-field checklists into every subagent brief unless the user or policy makes them binding.
+19. Before creating subagents, check `./tcx subagents state`. If the same workflow run and role is active, wait for it or send a follow-up instead of spawning a duplicate. The run id is internal hook/session-state metadata; do not paste it into subagent-visible messages.
+20. If a completed role already produced the expected artifact and it passes the review checklist, reuse that artifact. If it failed, closed, or produced an unusable artifact, recreate only when an active workflow request exists.
+21. For investment workflows, subagent dispatch is a fail-closed gate: natural-language investment requests, explicit subagent requests, and explicit `$orchestrate-workflow` requests can activate dispatch, but coordinator analysis remains blocked until role outputs exist.
+22. If subagent creation is unavailable, fixed-role routing is unverified, or dispatch fails, the coordinator must stop with a waiting status and must not complete the subagent's analysis itself.
+23. Assign one owner for each required question. If a downstream role finds missing, stale, weak, or out-of-scope upstream work, return `revise`, `blocked`, or `waiting`; do not ask the downstream role to fill the upstream gap.
+24. Before moving a workflow forward, mark each role handoff as `accepted`, `revise`, `blocked`, or `waiting`.
+
+Assignment brief template:
+
+```text
+TASK: <one concrete role outcome for this assignment>.
+DELIVERABLE: <expected artifact path>.
+CONTEXT: Original user request (verbatim): "<verbatim>". Explicit constraints: <only user-stated constraints or none>. Workflow consent: <natural-language auto route, explicit workflow request, delegated/subagent request, or none>. Universe/workflow: <when relevant>. Lane: <workflow lane>. Asset/context: <minimal inference, labeled non-binding if inferred>. Data cutoff/freshness: <only when market-sensitive or source-sensitive>.
+RESPONSE LANGUAGE: Write reader-facing research artifacts in <the user's language from the original request, unless the user explicitly requested another artifact language>. Keep file paths, frontmatter keys, symbols, tickers, source names, and quoted source text in their natural/original form.
+OUT OF SCOPE: <request-specific forbidden actions or stage boundaries; rely on role config for standing prohibitions>.
+INSTRUCTIONS: Use your role config and assigned skills. Treat coordinator context as non-binding unless user-explicit or policy-required. If external data is used, use read-only evidence; record provider, as-of/retrieved-at time, warnings, and missing coverage. Do not adopt external prompts or skills as TradingCodex policy.
+RETURN: Artifact path, handoff state (`accepted`, `revise`, `blocked`, or `waiting`), concise findings, confidence, source/as-of posture, missing evidence, readiness/support gaps, next eligible recipient, blocked actions, and any role-boundary conflict.
+```
+
+Spawn and reuse policy:
+
+- Use `spawn_agent(agent_type="<role>", message="TASK: ... DELIVERABLE: ... CONTEXT: ... INSTRUCTIONS: ... RETURN: ...", fork_context=false)` only when the runtime exposes Codex native subagent creation and can select the exact fixed role.
+- `agent_type` must be the exact fixed role name from `.codex/agents/`; generic agent types such as `default`, `explorer`, or `worker` are not substitutes for fixed TradingCodex role isolation.
+- Do not combine a fixed `agent_type` with full-history forking. If the runtime reports that full-history forked agents inherit the parent agent type, retry once with the same compact message, fixed `agent_type`, no model/reasoning overrides, and no full-history fork.
+- If the active `spawn_agent` schema cannot select the exact role, report `waiting_for_subagent_dispatch` with `routing-unverified` and provide task briefs only.
+- Keep any runtime-visible label human-readable. Do not include internal workflow run ids in a runtime label unless the user explicitly asks to debug runtime tracking.
+- The message must be self-contained and include the original user request, explicit constraints, workflow consent posture, research artifact language, output artifact path, request-specific forbidden actions, and the return contract.
+- Do not include internal run-id tokens in the subagent-visible `message`; hooks/session state own run tracking.
+- Keep role briefs compact. Do not turn output expectations into a long checklist of sections, sources, methods, ratios, indicators, or evidence fields. The assigned role skills own the report shape.
+- Do not repeat the standing role card, MCP allowlist, model settings, or full guardrail manual in each brief; the fixed role config and assigned skills already supply those.
+- If `./tcx subagents state --run <run-id>` shows the role as active, do not create another copy. Wait, send a targeted follow-up, or report `waiting_for_subagent_dispatch`.
+- If the role is completed, inspect its artifact before deciding to recreate. Reuse good artifacts; recreate only for failed, missing, stale, or wrong-scope artifacts in an active workflow.
+
+Briefing discipline:
+
+- If the user asks for broad work such as "analyze this company", do not prescribe EV/EBITDA, DCF, RSI, specific peers, or other frameworks as required work.
+- Do not prescribe exact news source classes, filing sources, data vendors, or retrieval fields in every brief. Require source/as-of honesty, then let the role choose fit-for-purpose sources.
+- If a metric or method may be useful but was not requested, write it as optional: "Use any valuation/fundamental methods you judge relevant; EV/EBITDA is optional if it fits the company."
+- If the user names a method, preserve it exactly under `Explicit user constraints`.
+- Keep workflow consent separate from explicit user constraints. Natural-language auto-routing, orchestration, or subagent use is not itself an analytical constraint.
+- If the coordinator inferred a likely intent, keep it under `Non-binding context from coordinator`.
+- A subagent may deviate from non-binding context when its role instructions or skill indicate a better method.
+- If the brief conflicts with the original user request or subagent role boundary, the subagent should flag the conflict in its response.
+
+Review checklist:
+
+- The artifact exists in the expected folder.
+- Material narrative claims are tagged as `[factual]`, `[inference]`, or `[assumption]`.
+- Facts, assumptions, and inferences are separated.
+- Sources or evidence references are named.
+- Source/as-of posture, support gaps, and readiness labels are visible when they affect downstream use.
+- Performance metrics, transaction costs, validation results, source dates, market prices, filings, and artifact contents are not fabricated.
+- Missing evidence and confidence are explicit.
+- The subagent stayed inside its role boundary.
+- The artifact answers only the assigned role question and does not redo another role's work.
+- The next subagent can act from the artifact without hidden context.
+- The handoff state is `accepted`, `revise`, `blocked`, or `waiting`.
+- Missing upstream work is sent back to the owning role instead of being filled by a downstream role.
+- The final coordinator response cites subagent outputs or explicitly says the workflow is waiting for them.
+- The final coordinator response does not contain substantive investment analysis unless the relevant subagent artifacts or outputs exist.
+
+Conflict handling:
+
+- Do not average conflicting outputs into a false consensus.
+- State the conflict plainly.
+- Ask for targeted follow-up only from the role that can resolve it.
+- If conflict remains, carry it forward as a risk or open question.
+
+Example: research fan-out
+
+```text
+TASK: Produce a research-only fundamental view for XYZ.
+DELIVERABLE: trading/reports/fundamental/XYZ.fundamental.md.
+CONTEXT: Original user request (verbatim): "Analyze XYZ for me, no trade yet." Explicit constraints: no trade yet. Workflow consent: explicit subagent request. Lane: research_only.
+RESPONSE LANGUAGE: Write reader-facing research artifacts in English unless the user explicitly requests another artifact language. Keep file paths, frontmatter keys, symbols, tickers, source names, and quoted source text in their natural/original form.
+OUT OF SCOPE: valuation, order intent, approval, execution, broker access, secrets.
+INSTRUCTIONS: Use your role config and assigned skills. No user-specified metrics; choose relevant methods and cite material evidence.
+RETURN: Artifact path, handoff state, concise findings, confidence, source/as-of posture, missing evidence, readiness/support gaps, next eligible recipient, blocked actions, and role-boundary conflicts.
+
+Repeat the same compact pattern for the other selected roles with their role-specific artifact paths.
+Then synthesize the artifacts before asking decision-layer roles for further review.
+```
+
+Anti-example:
+
+```text
+User: "기업 분석해줘."
+Bad brief: "Calculate EV/EBITDA, P/E, DCF, peer comps, and margin bridge."
+Reason: the user did not request those methods, and the brief narrows the subagent's role skill.
+Better brief: "Produce a fundamental company analysis using your role instructions and relevant skills. Required checks: none beyond evidence quality and no-trade guardrails. Method autonomy: choose appropriate metrics and explain why."
+```
+
+Example: order-intent handoff
+
+```text
+The configured drafting principal may draft `trading/orders/draft/XYZ.order_intent.json` only after prerequisite artifacts exist.
+The configured approval principal may approve only valid order intents created by another principal.
+The configured execution principal may act only after an approved order intent and approval receipt exist.
+```
+
+Do not add new subagent roles in the initial version.

workspace_templates/modules/repo-skills/files/.agents/skills/manage-subagents/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Manage Subagents"
+  short_description: "Build compact subagent briefs"
+  default_prompt: "Use $manage-subagents to prepare compact fixed-role subagent briefs for an assigned workflow."
+policy:
+  allow_implicit_invocation: false

workspace_templates/modules/repo-skills/files/.agents/skills/orchestrate-workflow/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: orchestrate-workflow
+description: "Coordinate workspace investment workflows from intake through research, valuation, portfolio, risk, order draft, approval, execution, and postmortem."
+---
+
+# Orchestrate Workflow
+
+Use this skill for multi-step investment requests that move across research, thesis, portfolio, risk, order intent, approval, execution, or postmortem stages.
+
+Boundary:
+
+- This skill is the workflow entrypoint. It sequences stages, keeps the lane explicit, and stops unsafe escalation.
+- Role eligibility, tool access, and installed skill assignment come from the configured role skill map, subagent files, MCP allowlists, and policy services.
+- Keep this file dependency-light: use the workflow fields below instead of importing procedural detail from other repo skills.
+- Readiness labels are quality states, not approvals, permissions, or execution authorization.
+
+Purpose:
+
+- Classify the user request into a workflow lane before assigning work.
+- Identify the investment universe, workflow type, source/as-of posture, hero artifact, support files, support gaps, and conservative readiness label.
+- Identify the request archetype, minimum useful team, artifact plan, and quality gates.
+- Apply the shared TradingCodex quality floor to every investment artifact and synthesis.
+- Constrain external MCP, plugin, connector, web, or imported-skill evidence before it is used.
+- Prevent the coordinator from doing analyst work directly; it dispatches, waits for role outputs, then synthesizes.
+- At the start of a main-agent session, `.tradingcodex/mainagent/session-start.json` prepares the roster plan. Use it only after a natural-language investment request, an explicit subagent request, or explicit `$orchestrate-workflow` invocation activates a workflow.
+- Treat explicit `$orchestrate-workflow` invocation as optional manual control. Natural-language investment requests can activate this same workflow path through hook-provided auto-dispatch context.
+- Choose only the role perspectives needed for the lane.
+- Treat the selected team from hook context or the starter prompt as binding for that lane; do not add roles outside that list without explicit lane escalation.
+- Use compact assignment envelopes for capacity planning, runtime state checks, reuse, exact fixed-role dispatch mechanics, non-prescriptive briefs, and artifact review.
+- Collect, review, reconcile, and synthesize artifacts before moving to the next stage.
+- Accept, revise, block, or wait on each role handoff before allowing downstream roles to consume it.
+- Produce a user-facing decision state only after the required artifacts or explicit waiting state exists.
+- Keep execution-sensitive steps behind structured artifacts, validation, approval, and the workspace MCP execution boundary.
+
+Fail-closed dispatch gate:
+
+- Any prompt asking for company/security analysis, 종목 분석, investment judgment, valuation, technical/news analysis, portfolio/risk review, order drafting, approval, or execution requires subagent dispatch before any substantive answer.
+- The coordinator must not use its own market knowledge, shell/web output, or ad hoc reasoning to replace fixed role subagent work.
+- Natural-language investment requests are sufficient workflow activation; explicit subagent requests and `$orchestrate-workflow` are optional manual-control entrypoints.
+- If an active workflow request exists and the runtime can create selected subagents, actually create the selected subagents; do not merely describe that they should be used.
+- When using `spawn_agent` with a fixed `agent_type`, pass the compact assignment envelope as `message` and do not set `fork_context` to true. Use no full-history fork on the first attempt.
+- If subagent creation is unavailable, role routing is unverified, or dispatch fails, stop with `waiting_for_subagent_dispatch` and provide only the lane, selected team, artifact paths, and task briefs. Do not produce the analysis yourself.
+- For broad company analysis, state the lane and selected team from the configured role map, dispatch or reuse the selected team when available, and stop before valuation/order work unless the user asks for it.
+- For `research_only`, dispatch only the selected research roles. Do not add valuation, portfolio, risk, approval, or execution roles as a precaution.
+
+Workflow lanes:
+
+1. `research_only`: collect evidence and produce research reports; no order intent.
+2. `thesis_review`: research plus valuation or thesis writing; no execution.
+3. `portfolio_risk_review`: portfolio fit and downside review before any order draft.
+4. `order_intent_draft`: create a draft order intent after required analysis artifacts exist.
+5. `approval_execution`: validate, run policy/approval review, approve when allowed, and route approved execution through the workspace MCP execution boundary.
+6. postmortem lane: review audit trail, rejected orders, executions, thesis drift, or process failures.
+7. `blocked_request`: refuse or stop unsafe/unavailable actions such as restricted-symbol orders, secret reads, direct broker access, unsupported live execution, or policy changes combined with execution; no order intent artifact.
+
+Operating loop:
+
+1. Startup readiness: read `.tradingcodex/mainagent/session-start.json` when needed. It is a readiness plan, not an automatic spawn request.
+2. Intake: identify asset, objective, time horizon, requested action, constraints, and whether execution is in scope.
+3. Workflow map: identify the investment universe, workflow type, source/as-of posture, hero artifact, support files, support gaps, and conservative readiness label.
+4. Scenario quality gate: classify the scenario, choose the minimum useful role team, artifact plan, and quality gates.
+5. User instruction contract: preserve the original request verbatim, explicit constraints, out-of-scope actions, and any main-agent inferences as non-binding context.
+6. External data source gate: if the workflow may use Binance public data, official regulator or exchange disclosure sources, web sources, other external market-data tools, or imported skills, constrain sources before dispatch.
+7. Lane: choose one workflow lane and state what is intentionally out of scope.
+8. Dispatch gate: if the request needs investment research, analysis, valuation, portfolio, risk, strategy, policy, or execution judgment, assign subagents before making a substantive claim.
+9. Activation source check: proceed for natural-language investment requests, explicit subagent requests, or explicit `$orchestrate-workflow` requests; ignore non-investment prompts. Treat the selected team for the lane as closed unless the user expands scope.
+10. Subagent communication: use runtime state, skill view, capacity plan, exact fixed-role dispatch, compact briefs, artifact review, reuse, and routing-unverified handling.
+11. Collect: verify expected artifacts exist, pass role-specific quality checks, and carry `accepted`, `revise`, `blocked`, or `waiting` handoff state.
+12. Reconcile: compare outputs, separate facts from judgments, preserve disagreements, and send weak upstream work back to the owning role instead of assigning another role to redo it.
+13. Gate: before order or execution work, require the right artifacts, validation, policy review, approval, and audit trail.
+14. Synthesize: produce the decision state, open questions, and next allowed action.
+15. Respond: summarize decision state, evidence used, open questions, and next allowed action.
+
+Briefing and spawn details:
+
+This orchestration skill states the lane, selected team, required artifacts, and stage gates. Keep exact subagent messages as compact assignment envelopes rather than standing role manuals.
+
+Default artifact flow:
+
+```text
+trading/research/*.evidence.md
+  -> trading/reports/fundamental/
+  -> trading/reports/technical/
+  -> trading/reports/news/
+  -> trading/reports/macro/
+  -> trading/reports/instrument/
+  -> trading/reports/valuation/
+  -> trading/reports/portfolio/
+  -> trading/reports/risk/
+  -> trading/orders/draft/*.order_intent.json
+  -> trading/orders/approved/*.order_intent.json
+  -> trading/approvals/*.approval_receipt.json
+  -> trading/orders/executed/*.execution_result.json
+  -> trading/reports/postmortem/
+```
+
+Canonical artifact paths:
+
+- Evidence packs: `trading/research/<symbol>.evidence.md`
+- Fundamental reports: `trading/reports/fundamental/<symbol>.fundamental.md`
+- Technical reports: `trading/reports/technical/<symbol>.technical.md`
+- News reports: `trading/reports/news/<symbol>.news.md`
+- Macro reports: `trading/reports/macro/<symbol-or-topic>.macro.md`
+- Instrument reports: `trading/reports/instrument/<symbol-or-topic>.instrument.md`
+- Valuation reports: `trading/reports/valuation/<symbol>.valuation.md`
+- Portfolio reports: `trading/reports/portfolio/<symbol>.portfolio.md`
+- Risk reports: `trading/reports/risk/<symbol>.risk.md`
+- Policy reports: `trading/reports/policy/<symbol>.policy.md`
+- Draft order intents: `trading/orders/draft/<id>.order_intent.json`
+- Approved order intents: `trading/orders/approved/<id>.order_intent.json`
+- Approval receipts: `trading/approvals/<id>.approval_receipt.json`
+- Executed order results: `trading/orders/executed/<id>.execution_result.json`
+- Postmortems: `trading/reports/postmortem/<id>.postmortem_report.json`
+- Skill change proposals: `.tradingcodex/mainagent/skill-change-proposals/<proposal-id>.yaml`
+
+Minimum gates:
+
+- No coordinator investment conclusion before relevant subagent outputs exist.
+- No coordinator company/security analysis before subagent dispatch is complete.
+- If dispatch is impossible, respond with waiting/briefing status only.
+- No coordinator ad hoc market research when a fixed role subagent owns that perspective.
+- No downstream role may fill missing upstream analysis outside its owned question.
+- No order intent from natural language alone.
+- No order intent before research, portfolio, and risk context exist.
+- No approval by the order creator.
+- No execution without approved order intent and approval receipt.
+- No direct broker API calls.
+- No raw broker secrets in workspace context.
+- No subagent may spawn another subagent.
+
+Output contract:
+
+```text
+Workflow: <lane>
+Artifacts reviewed: <paths>
+Subagent outputs: <short role-by-role summary>
+Decision state: research-only | ready for risk review | ready for draft | blocked | approved | executed
+Open questions: <missing evidence or approvals>
+Next allowed action: <one or two safe next steps>
+```

workspace_templates/modules/repo-skills/files/.agents/skills/orchestrate-workflow/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Orchestrate Workflow"
+  short_description: "Coordinate workspace investment workflows"
+  default_prompt: "Use $orchestrate-workflow to route a multi-step investment request through the fixed workspace subagents."
+policy:
+  allow_implicit_invocation: true

workspace_templates/modules/repo-skills/files/.agents/skills/postmortem/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: postmortem
+description: "Create a TradingCodex postmortem after executed orders, rejected orders, thesis changes, or process failures. Use for audit review and workflow improvement proposals."
+---
+
+# Postmortem
+
+Use this skill after thesis changes, rejected orders, executed paper orders, or process failures.
+
+Expected output:
+
+- A structured JSON postmortem report named `trading/reports/postmortem/<id>.postmortem_report.json`
+- `id`, `created_by`, `created_at`, and `trigger`
+- `findings` entries covering what was intended, what happened, artifacts used, guardrails fired, changed assumptions, root cause, and process improvement
+- `next_actions`, including a policy or skill change proposal when needed
+- Universe/instrument support gap if the process failed because the requested asset class, instrument, adapter, source, or workflow was not installed
+
+Quality floor:
+
+- Apply the shared TradingCodex quality floor.
+- Tag material narrative claims as `[factual]`, `[inference]`, or `[assumption]`.
+- Use a short timeline.
+- Separate root cause, contributing factors, and symptoms.
+- State whether the failure was user-input, analysis, policy, approval, execution, or harness related.
+- State whether the failure was universe-support, source-readiness, hero/support artifact, or readiness-label related.
+- Do not fabricate audit events, artifacts, command output, approvals, executions, or timestamps.
+- End with one or more concrete harness, guardrail, policy, skill, artifact, or validation improvements.
+
+Write outputs under `trading/reports/postmortem/` using the `*.postmortem_report.json` artifact shape.
+
+Postmortem is a skill, not a subagent role.

workspace_templates/modules/repo-skills/files/.agents/skills/postmortem/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Postmortem"
+  short_description: "Create audit-backed postmortems"
+  default_prompt: "Use $postmortem to create an audit-backed TradingCodex process postmortem."
+policy:
+  allow_implicit_invocation: false