chore(dev): add quantmind-dev skill and align contributor instructions

.agents/skills/quantmind-dev/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: quantmind-dev
+description: Contributor workflow for the QuantMind codebase. Covers commit format, pull request format, and component development across quantmind/ modules (knowledge, configs, preprocess, flows, mind, utils) with tests, examples, and verification. Use when committing, opening a PR, or implementing/refactoring QuantMind code.
+---
+
+# QuantMind Dev
+
+Development workflow for contributing to the QuantMind codebase.
+
+## Start Here
+
+1. Read the repository root `AGENTS.md` or `CLAUDE.md` for the stable
+   architecture constraints and the module map.
+2. Pick exactly one workflow reference below; do not load the others.
+
+## Select Workflow
+
+- Committing staged work → `references/commit.md`
+- Opening or updating a pull request → `references/pull-request.md`
+- Implementing or refactoring anything under `quantmind/` →
+  `references/develop-components.md` (read it **before** writing code)
+
+A feature task usually chains all three: develop → commit → pull request.
+
+## Rules
+
+- `bash scripts/verify.sh` is the single "shippable" gate. CI runs the same
+  script; run it before every push and before marking a PR ready.
+- Never bypass pre-commit / pre-push hooks (`--no-verify`) unless the user
+  explicitly authorizes it.
+- New features ship with a unit test and a focused example (see
+  `references/develop-components.md`).
+- This skill is mirrored under `.agents/skills/quantmind-dev/` and
+  `.claude/skills/quantmind-dev/`; the copies are identical. When changing
+  the skill, update both in the same change.
+
+## Boundaries
+
+- This skill is for contributing to QuantMind itself. It does not cover
+  using QuantMind as a library in your own project.
+- Product decisions (new modules, new dependencies, API redesigns) need an
+  issue and maintainer discussion first; do not encode them here.

.agents/skills/quantmind-dev/references/commit.md

@@ -0,0 +1,57 @@
+# Commit Workflow
+
+How to commit work in the QuantMind repository.
+
+## Message Format
+
+English, [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+<type>(<scope>): <summary>
+```
+
+- **type**: `feat` | `fix` | `refactor` | `docs` | `test` | `chore`
+- **scope**: optional but preferred — use the module or area the change
+  touches, matching existing history (`feat(memory): ...`,
+  `chore(verify): ...`, `docs(news): ...`). Omit the scope only for
+  repo-wide changes (`feat: flows + magic apex layer`).
+- **summary**: imperative, lower-case start, no trailing period.
+
+Examples from history:
+
+```text
+feat: preprocess fetch+format module (PR4 of OpenAI Agents SDK migration) (#75)
+chore(verify): add scripts/verify.sh + ruff/basedpyright/import-linter/pytest --cov harness (#73)
+fix(test): Prevent creation of `test_data` directory during unit tests (#41)
+```
+
+## One Logical Change per Commit
+
+Keep each commit focused on a single logical change. Split unrelated edits
+(e.g. a bug fix discovered while building a feature) into separate commits.
+Do not mix mechanical reformatting with behavior changes.
+
+## Before Committing
+
+1. Inspect exactly what you are about to commit:
+
+   ```bash
+   git status
+   git diff --staged
+   ```
+
+   Confirm no unintended files (scratch scripts, local configs, large
+   artifacts) are staged.
+
+2. Run verification appropriate to the change:
+   - during development: targeted tests, e.g. `pytest tests/<module>/`
+   - before push / handoff: `bash scripts/verify.sh` (canonical gate)
+
+3. Commit. Pre-commit hooks run ruff format/check and file hygiene checks;
+   the pre-push hook runs the full `scripts/verify.sh`.
+
+## Hooks
+
+If a hook fails, fix the underlying issue and commit again. Never use
+`git commit --no-verify` or otherwise bypass hooks unless the user has
+explicitly authorized it for that specific commit.

.agents/skills/quantmind-dev/references/develop-components.md

@@ -0,0 +1,105 @@
+# Component Development Workflow
+
+How to implement or refactor code under `quantmind/`. Read this before
+writing code; the architecture constraints in root `AGENTS.md` / `CLAUDE.md`
+apply throughout.
+
+## General Loop
+
+1. **Find the nearest existing pattern.** Locate the closest analogous
+   implementation in the target module and follow its structure, naming,
+   and test layout. Consistency beats novelty.
+2. **Check the dependency contract** for your module (table below) before
+   adding any import. `lint-imports` enforces these; if your design needs a
+   forbidden import, the design is wrong — restructure, do not work around
+   the contract.
+3. **Implement small and flat.** Pure functions over classes; `Protocol`
+   over ABC; no meaningless wrappers (a method must add logic, abstraction,
+   or a side effect beyond the call it wraps). No premature abstractions —
+   extract shared code when the second real caller appears, not before.
+4. **Add the unit test and the example** (sections below).
+5. **Update the public surface** if needed: module `__init__.py` exports
+   and user-facing docs (`README.md`, `docs/`) for user-visible features.
+6. **Verify**: targeted `pytest tests/<module>/` while iterating;
+   `bash scripts/verify.sh` before handoff.
+
+## Module Routing
+
+### Dependency contracts (enforced by import-linter)
+
+| Module | May import from `quantmind.*` |
+|--------|-------------------------------|
+| `quantmind/utils/` | nothing (leaf) |
+| `quantmind/knowledge/` | nothing (leaf) |
+| `quantmind/configs/` | `knowledge` only |
+| `quantmind/preprocess/` | `utils` only |
+| `quantmind/flows/`, `quantmind/magic.py` | apex — may import all of the above |
+
+### `quantmind/knowledge/` — data standard
+
+- Pydantic models, `frozen=True`, `extra="forbid"`.
+- Every `BaseKnowledge` subclass **must** require `as_of: datetime`
+  (financial time-sensitivity is mandatory) and a typed `source: SourceRef`
+  (no bare strings), and **must** override `embedding_text()`.
+- Pick one shape: `FlattenKnowledge` (atomic card), `TreeKnowledge`
+  (hierarchical artifact), or `GraphKnowledge` (placeholder). Whole-document
+  objects are `TreeKnowledge` even when a flatten card exists alongside
+  (e.g. `Paper` vs `PaperKnowledgeCard`).
+
+### `quantmind/configs/` — flow cfg + typed inputs
+
+- Extend `BaseFlowCfg`; inputs are discriminated-union Pydantic types.
+- Never `Dict[str, Any]` in signatures — model it.
+
+### `quantmind/preprocess/` — deterministic data prep
+
+- Fetch / format / clean / time utilities: deterministic, no LLM calls.
+- Return frozen dataclasses (`Fetched`, `RawPaper`, ...), not dicts.
+- Surface the common path at the package root (`from quantmind.preprocess
+  import fetch_arxiv`), keep explicit submodule paths working.
+
+### `quantmind/flows/` and `quantmind/magic.py` — apex layer
+
+- Flows are pure `async def` functions, not classes; state passes as
+  arguments; side effects go through explicit hooks.
+- Use the OpenAI Agents SDK directly (`Agent`, `@function_tool`,
+  `output_type=`); never wrap `from agents import ...` in a facade.
+- Fan-out goes through `batch_run` (bounded concurrency, error policy);
+  `batch_run` rejects `memory=` at the signature layer by design.
+
+### `quantmind/mind/` — cognitive layer
+
+- Lands via the Agents SDK migration (tracking: #71). Backends implement
+  the `Memory` Protocol with granular `tools()`, `mcp_servers()`,
+  `run_hooks()`, `reset()` — each may return an empty list; do not force
+  MCP on every implementation.
+
+### `quantmind/utils/`
+
+- Logger only. New general-purpose helpers need maintainer sign-off via an
+  issue first; the default answer is "put it in the module that uses it".
+
+## Tests
+
+- Location mirrors the module: `tests/<module>/test_<topic>.py`.
+- Subclass `unittest.TestCase` (run via pytest).
+- Mock external services (network, LLM APIs, filesystem where practical);
+  tests must pass offline.
+- Cover the success path **and** at least one failure path per public
+  function.
+- Coverage floor is enforced by `pytest --cov` in `scripts/verify.sh`; new
+  code should not lower branch coverage.
+
+## Examples
+
+- One focused example per new feature under `examples/<module>/`
+  (create the directory if it does not exist yet).
+- Demo the simple, common usage — one scenario per file, runnable as
+  `python examples/<module>/<name>.py`, minimal setup.
+
+## Documentation
+
+- Docstrings: English, Google style, required on public functions and
+  models.
+- User-visible behavior changes update `README.md` (usage section) and
+  `docs/` where applicable.

.agents/skills/quantmind-dev/references/pull-request.md

@@ -0,0 +1,51 @@
+# Pull Request Workflow
+
+How to open and maintain a pull request against QuantMind.
+
+## Before Opening
+
+1. Branch from `master`; keep the PR small and focused — one PR equals one
+   reviewable change (see
+   [Google eng practices on small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)).
+2. Run the canonical gate and make sure it is green:
+
+   ```bash
+   bash scripts/verify.sh
+   ```
+
+   CI runs the exact same script; do not open (or mark ready) a PR with a
+   red local run.
+
+## Title
+
+English, Conventional Commit style, same format as commit messages:
+
+```text
+<type>(<scope>): <summary>
+```
+
+Examples: `feat(preprocess): add RSS fetcher`, `fix(flows): handle empty
+batch input`, `docs(readme): update quick start`.
+
+## Body
+
+Written in English (external audiences read it: contributors, search
+indexers, future maintainers). Follow `.github/PULL_REQUEST_TEMPLATE.md`
+and make sure the body covers:
+
+1. **What changed and why** — a short summary; link the design discussion
+   if one exists.
+2. **Related issue** — reference it when one exists (`Closes #NN` /
+   `Part of #NN`).
+3. **Verification performed** — state what you ran (e.g.
+   `bash scripts/verify.sh` green; targeted `pytest tests/<module>/`;
+   manual example run) so the reviewer does not have to guess.
+
+Keep the template checklist and remove items that do not apply.
+
+## Review and Merge
+
+- Assign relevant reviewers when you know who owns the area.
+- Address review comments with follow-up commits (no force-push rewrites of
+  reviewed history unless asked).
+- After merge: switch back to `master`, pull, and delete the feature branch.

.claude/skills/quantmind-dev/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: quantmind-dev
+description: Contributor workflow for the QuantMind codebase. Covers commit format, pull request format, and component development across quantmind/ modules (knowledge, configs, preprocess, flows, mind, utils) with tests, examples, and verification. Use when committing, opening a PR, or implementing/refactoring QuantMind code.
+---
+
+# QuantMind Dev
+
+Development workflow for contributing to the QuantMind codebase.
+
+## Start Here
+
+1. Read the repository root `AGENTS.md` or `CLAUDE.md` for the stable
+   architecture constraints and the module map.
+2. Pick exactly one workflow reference below; do not load the others.
+
+## Select Workflow
+
+- Committing staged work → `references/commit.md`
+- Opening or updating a pull request → `references/pull-request.md`
+- Implementing or refactoring anything under `quantmind/` →
+  `references/develop-components.md` (read it **before** writing code)
+
+A feature task usually chains all three: develop → commit → pull request.
+
+## Rules
+
+- `bash scripts/verify.sh` is the single "shippable" gate. CI runs the same
+  script; run it before every push and before marking a PR ready.
+- Never bypass pre-commit / pre-push hooks (`--no-verify`) unless the user
+  explicitly authorizes it.
+- New features ship with a unit test and a focused example (see
+  `references/develop-components.md`).
+- This skill is mirrored under `.agents/skills/quantmind-dev/` and
+  `.claude/skills/quantmind-dev/`; the copies are identical. When changing
+  the skill, update both in the same change.
+
+## Boundaries
+
+- This skill is for contributing to QuantMind itself. It does not cover
+  using QuantMind as a library in your own project.
+- Product decisions (new modules, new dependencies, API redesigns) need an
+  issue and maintainer discussion first; do not encode them here.

.claude/skills/quantmind-dev/references/commit.md

@@ -0,0 +1,57 @@
+# Commit Workflow
+
+How to commit work in the QuantMind repository.
+
+## Message Format
+
+English, [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+<type>(<scope>): <summary>
+```
+
+- **type**: `feat` | `fix` | `refactor` | `docs` | `test` | `chore`
+- **scope**: optional but preferred — use the module or area the change
+  touches, matching existing history (`feat(memory): ...`,
+  `chore(verify): ...`, `docs(news): ...`). Omit the scope only for
+  repo-wide changes (`feat: flows + magic apex layer`).
+- **summary**: imperative, lower-case start, no trailing period.
+
+Examples from history:
+
+```text
+feat: preprocess fetch+format module (PR4 of OpenAI Agents SDK migration) (#75)
+chore(verify): add scripts/verify.sh + ruff/basedpyright/import-linter/pytest --cov harness (#73)
+fix(test): Prevent creation of `test_data` directory during unit tests (#41)
+```
+
+## One Logical Change per Commit
+
+Keep each commit focused on a single logical change. Split unrelated edits
+(e.g. a bug fix discovered while building a feature) into separate commits.
+Do not mix mechanical reformatting with behavior changes.
+
+## Before Committing
+
+1. Inspect exactly what you are about to commit:
+
+   ```bash
+   git status
+   git diff --staged
+   ```
+
+   Confirm no unintended files (scratch scripts, local configs, large
+   artifacts) are staged.
+
+2. Run verification appropriate to the change:
+   - during development: targeted tests, e.g. `pytest tests/<module>/`
+   - before push / handoff: `bash scripts/verify.sh` (canonical gate)
+
+3. Commit. Pre-commit hooks run ruff format/check and file hygiene checks;
+   the pre-push hook runs the full `scripts/verify.sh`.
+
+## Hooks
+
+If a hook fails, fix the underlying issue and commit again. Never use
+`git commit --no-verify` or otherwise bypass hooks unless the user has
+explicitly authorized it for that specific commit.