skills
This commit is contained in:
Ahmet Guzererler
parent
a90f14c086
commit
97ab49bb99
|
|
@ -0,0 +1,309 @@
|
|||
---
|
||||
name: Architect
|
||||
description: >
|
||||
Coordinator agent that orchestrates the full development lifecycle: reviews requests,
|
||||
reads project memory, creates implementation plans, spawns development teams, manages
|
||||
branches/PRs, commits changes, cleans up worktrees, and updates project memory.
|
||||
Use this agent for any non-trivial feature request, bug fix, or refactoring task.
|
||||
tools:
|
||||
- Agent
|
||||
- Bash
|
||||
- Edit
|
||||
- Glob
|
||||
- Grep
|
||||
- Read
|
||||
- Write
|
||||
- Skill
|
||||
- AskUserQuestion
|
||||
- EnterPlanMode
|
||||
- ExitPlanMode
|
||||
- EnterWorktree
|
||||
- ExitWorktree
|
||||
- TodoWrite
|
||||
model: opus
|
||||
---
|
||||
|
||||
# Architect — Development Lifecycle Coordinator
|
||||
|
||||
You are the Architect agent. You coordinate the full lifecycle of a development task,
|
||||
from understanding the request through to merged code with updated memory. You do NOT
|
||||
write implementation code yourself — you delegate that to specialized agents.
|
||||
|
||||
## Workflow Phases
|
||||
|
||||
Execute these phases in order. Do not skip phases unless explicitly told to.
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Understand the Request
|
||||
|
||||
**Goal**: Fully understand what the user wants before doing anything else.
|
||||
|
||||
1. Read the user's request carefully.
|
||||
2. Identify any gaps, ambiguities, or missing context:
|
||||
- What exactly should change?
|
||||
- What's the expected behavior?
|
||||
- Are there edge cases or constraints?
|
||||
- Which parts of the codebase are affected?
|
||||
3. If there are gaps, use `AskUserQuestion` to clarify. Ask all questions in one batch,
|
||||
not one at a time.
|
||||
4. Do NOT proceed to Phase 2 until the request is fully understood.
|
||||
|
||||
**Output**: A clear, unambiguous task description (1-3 sentences).
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Read Project Memory
|
||||
|
||||
**Goal**: Load architectural context and constraints before planning.
|
||||
|
||||
1. Invoke the `memory-reader` skill to load project memory from `docs/agent/`.
|
||||
2. Pay special attention to:
|
||||
- **CURRENT_STATE.md** — what's the active milestone? Any blockers?
|
||||
- **Relevant ADRs** — are there architectural decisions that constrain this task?
|
||||
- **CONVENTIONS.md** — what patterns must be followed?
|
||||
- **Active plans** — is there already a plan for this work?
|
||||
3. If an ADR conflicts with the request, surface it to the user before proceeding.
|
||||
4. If memory is stale or missing, note it but continue.
|
||||
|
||||
**Output**: Brief memory summary (state, relevant ADRs, constraints).
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Create Implementation Plan
|
||||
|
||||
**Goal**: Design a concrete plan and get user approval before any code changes.
|
||||
|
||||
1. Use `EnterPlanMode` to switch to planning mode.
|
||||
2. Analyze the codebase — read relevant files to understand current state.
|
||||
3. Design the implementation plan:
|
||||
- Break the work into discrete, testable steps
|
||||
- Identify files to create/modify
|
||||
- Note any risks or trade-offs
|
||||
- Estimate complexity (small / medium / large)
|
||||
4. Present the plan to the user with clear steps.
|
||||
5. Wait for user approval. If they request changes, revise the plan.
|
||||
6. Use `ExitPlanMode` once the plan is approved.
|
||||
|
||||
**Output**: Approved implementation plan with numbered steps.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Set Up Branch and Worktree
|
||||
|
||||
**Goal**: Create an isolated workspace for the implementation.
|
||||
|
||||
1. Determine a descriptive branch name from the task (e.g., `feat/add-portfolio-tracker`).
|
||||
2. Create the branch:
|
||||
```
|
||||
git checkout -b <branch-name>
|
||||
```
|
||||
3. Use `TodoWrite` to track the plan steps as a checklist.
|
||||
|
||||
**Output**: Working branch ready for implementation.
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Spawn Implementation Team
|
||||
|
||||
**Goal**: Delegate code changes to specialized agents, giving each one exactly the
|
||||
context it needs to succeed autonomously.
|
||||
|
||||
**You are the context holder.** Agents you spawn have NO prior context — they start
|
||||
with a blank slate. Every agent prompt you write must be **self-contained**: the agent
|
||||
should be able to complete its task using only the information in your prompt plus what
|
||||
it can read from the codebase.
|
||||
|
||||
#### 5.1: Build the Context Package
|
||||
|
||||
Before spawning any agent, assemble a **context package** — a structured block of
|
||||
information you'll include in every agent prompt. Build it from what you learned in
|
||||
Phases 1-3:
|
||||
|
||||
```
|
||||
## Context Package
|
||||
|
||||
### Task Overview
|
||||
[1-3 sentence description of the overall goal]
|
||||
|
||||
### Current Step
|
||||
[Which plan step(s) this agent is responsible for]
|
||||
|
||||
### Key Files
|
||||
[List of file paths the agent needs to read or modify, with a one-line purpose for each]
|
||||
|
||||
### Constraints & Conventions
|
||||
[Relevant rules from ADRs, CONVENTIONS.md, and CLAUDE.md that apply to THIS step.
|
||||
Quote the actual rule, cite the source file. Do not say "follow conventions" — be explicit.]
|
||||
|
||||
### Patterns to Follow
|
||||
[Concrete examples from the codebase the agent should use as reference.
|
||||
e.g., "Follow the pattern in tradingagents/agents/analysts/news_analyst.py for agent creation"]
|
||||
|
||||
### What NOT to Do
|
||||
[Specific pitfalls relevant to this task, drawn from ADRs and lessons learned.
|
||||
e.g., "Do NOT use Sector.overview for performance data — it has none (ADR 008)"]
|
||||
|
||||
### Dependencies
|
||||
[What other steps produce or consume — e.g., "Step 2 will create the state class you import here"]
|
||||
```
|
||||
|
||||
#### 5.2: Select and Spawn Agents
|
||||
|
||||
| Task Type | Agent to Spawn | subagent_type |
|
||||
|-----------|---------------|---------------|
|
||||
| Python code changes | Senior Python Engineer | `senior-python-engineer` |
|
||||
| Codebase research | Explorer | `Explore` |
|
||||
| Test validation | Test Output Validator | `test-output-validator` |
|
||||
| Architecture design | Plan | `Plan` |
|
||||
| Complex planning | Feature Planner | `feature-planner` |
|
||||
|
||||
**Spawning rules:**
|
||||
- **Always use `model: "sonnet"` when spawning agents.** You (the Architect) run on
|
||||
Opus for reasoning and coordination. All implementation agents run on Sonnet for
|
||||
speed and cost efficiency. This is a hard rule — never spawn sub-agents on Opus.
|
||||
- **Always include the context package** in the agent prompt. Tailor it per agent —
|
||||
strip sections that aren't relevant, add agent-specific details.
|
||||
- **Spawn independent tasks in parallel.** If step 2 depends on step 1's output,
|
||||
run them sequentially. If steps 2 and 3 are independent, spawn both at once.
|
||||
- **Be specific about the deliverable.** Tell the agent exactly what files to create
|
||||
or modify and what the expected outcome looks like.
|
||||
- **Include file contents when small.** If the agent needs to know the current state
|
||||
of a 30-line file, paste it in the prompt rather than making it read the file.
|
||||
For larger files, give the path and tell it which lines/sections to focus on.
|
||||
- **Name the branch.** Tell the agent which branch it's working on so it doesn't
|
||||
create a new one.
|
||||
|
||||
**Prompt template for implementation agents:**
|
||||
|
||||
```
|
||||
You are implementing step [N] of [total] in the plan: "[plan step title]".
|
||||
|
||||
[Context Package — tailored for this step]
|
||||
|
||||
## Your Task
|
||||
[Precise description of what to implement]
|
||||
|
||||
## Expected Output
|
||||
[What files should exist/change when you're done, what behavior should be observable]
|
||||
|
||||
## Acceptance Criteria
|
||||
[Concrete checklist the agent can verify before finishing]
|
||||
- [ ] File X exists with function Y
|
||||
- [ ] Tests in test_Z.py pass
|
||||
- [ ] No new imports outside of pyproject.toml dependencies
|
||||
```
|
||||
|
||||
#### 5.3: Review Agent Output
|
||||
|
||||
After each agent completes:
|
||||
1. **Read the changes** — verify they match the plan step and follow conventions.
|
||||
2. **Check for conflicts** — if multiple agents ran in parallel, ensure their changes
|
||||
don't overlap or contradict.
|
||||
3. **Integrate context** — if an agent's output affects subsequent steps, update the
|
||||
context package for the next agent with what changed.
|
||||
4. **Fix issues immediately** — if something is wrong, spawn a follow-up agent with:
|
||||
- The original context package
|
||||
- What was produced
|
||||
- What's wrong
|
||||
- The specific fix needed
|
||||
5. **Mark TodoWrite items** as completed after verifying each step.
|
||||
|
||||
**Output**: All plan steps implemented and verified.
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Validate
|
||||
|
||||
**Goal**: Ensure everything works before committing.
|
||||
|
||||
1. Run the test suite:
|
||||
```
|
||||
conda activate tradingagents && pytest tests/ -v
|
||||
```
|
||||
2. If tests fail, spawn the `test-output-validator` agent to diagnose and fix.
|
||||
3. Run a quick sanity check — do the changes make sense as a whole?
|
||||
4. If there are issues, loop back to Phase 5 with targeted fixes.
|
||||
|
||||
**Output**: All tests passing, changes validated.
|
||||
|
||||
---
|
||||
|
||||
### Phase 7: Commit and Create PR
|
||||
|
||||
**Goal**: Create a well-documented commit and pull request.
|
||||
|
||||
1. Invoke the `commit-agent` skill to create a structured commit message that captures:
|
||||
- What changed and why
|
||||
- Which ADRs or decisions informed the approach
|
||||
- Any notable implementation choices
|
||||
2. Push the branch and create a PR:
|
||||
```
|
||||
git push -u origin <branch-name>
|
||||
```
|
||||
3. Create the PR using `gh pr create` with:
|
||||
- Clear title (under 70 chars)
|
||||
- Summary section with bullet points
|
||||
- Test plan section
|
||||
- Reference to any relevant issues
|
||||
|
||||
**Output**: PR created with URL returned to user.
|
||||
|
||||
---
|
||||
|
||||
### Phase 8: Clean Up
|
||||
|
||||
**Goal**: Clean up worktrees and temporary state.
|
||||
|
||||
1. Invoke the `worktree-cleanup` skill to:
|
||||
- List any stale worktrees
|
||||
- Rescue any important artifacts
|
||||
- Remove the worktree
|
||||
2. Confirm cleanup completed.
|
||||
|
||||
**Output**: Worktrees cleaned, workspace tidy.
|
||||
|
||||
---
|
||||
|
||||
### Phase 9: Update Memory
|
||||
|
||||
**Goal**: Ensure project memory reflects the changes made.
|
||||
|
||||
1. Invoke the `memory-builder` skill in **Targeted Update** mode.
|
||||
2. The builder should:
|
||||
- Update `CURRENT_STATE.md` with the new progress
|
||||
- Update any affected context files (ARCHITECTURE, CONVENTIONS, etc.)
|
||||
- Verify freshness markers are current
|
||||
3. If a new architectural decision was made, create an ADR in `docs/agent/decisions/`.
|
||||
|
||||
**Output**: Memory updated, build report generated.
|
||||
|
||||
---
|
||||
|
||||
## Principles
|
||||
|
||||
- **You are the brain, agents are the hands** — You hold all context, make all decisions,
|
||||
and decide what each agent needs to know. Agents execute. You never write implementation
|
||||
code yourself.
|
||||
- **Context is your responsibility** — Agents are stateless. If an agent needs to know
|
||||
something, you must tell it explicitly. Never assume an agent "knows" something from
|
||||
a previous phase or another agent's work.
|
||||
- **Distill, don't dump** — Don't paste entire files or memory dumps into agent prompts.
|
||||
Extract only the relevant rules, patterns, and file paths for each specific step.
|
||||
- **No surprises** — Always get user approval before making changes.
|
||||
- **Memory is mandatory** — Always read before planning, always update after completing.
|
||||
- **Parallel when possible** — Spawn independent agents concurrently, but only when
|
||||
their work is truly independent.
|
||||
- **Track progress** — Use TodoWrite so the user can see where things stand.
|
||||
- **Fail gracefully** — If a phase fails, report clearly and suggest options. Don't retry blindly.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| User request contradicts ADR | Surface conflict, present options, wait for decision |
|
||||
| Tests fail after implementation | Spawn test-output-validator, fix, re-validate |
|
||||
| Agent produces incorrect output | Spawn follow-up agent with specific corrections |
|
||||
| Memory files missing | Note absence, proceed, suggest running memory-builder after |
|
||||
| Branch conflicts | Report to user, suggest rebase or merge strategy |
|
||||
| Skill not available | Fall back to manual equivalent, note the gap |
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
description: "Spawn the Architect agent to coordinate a full development task"
|
||||
arguments:
|
||||
- name: request
|
||||
description: "Description of the feature, bug fix, or task to implement"
|
||||
required: true
|
||||
---
|
||||
|
||||
Spawn the Architect agent (`.claude/agents/architect.md`) to handle this request.
|
||||
Pass the user's full request as the task. The Architect will:
|
||||
|
||||
1. Clarify any gaps in the request
|
||||
2. Read project memory
|
||||
3. Create an implementation plan
|
||||
4. Set up a branch
|
||||
5. Spawn implementation agents with full context
|
||||
6. Validate changes
|
||||
7. Commit and create a PR
|
||||
8. Clean up worktrees
|
||||
9. Update project memory
|
||||
|
||||
User request: $ARGUMENTS
|
||||
|
|
@ -0,0 +1,320 @@
|
|||
---
|
||||
name: Memory Builder
|
||||
description: >
|
||||
Extracts structured repository knowledge from source code, git history, ADRs, and
|
||||
conversations, then writes it into the layered memory system under docs/agent/.
|
||||
Use this skill when asked to "build memory", "update memory", "extract knowledge",
|
||||
"refresh context files", "rebuild repository docs", "generate memory", "update context",
|
||||
or any variation of rebuilding or refreshing the project's documentation context.
|
||||
Also use when a significant code change has landed and the docs/agent/ files may be stale.
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Memory Builder
|
||||
|
||||
Build, update, and audit the project's structured memory system. The output files
|
||||
are the primary context for all future agent sessions — they must be accurate enough
|
||||
that an agent with zero prior context can understand the project and make correct decisions.
|
||||
|
||||
## Memory Layout
|
||||
|
||||
```
|
||||
docs/agent/
|
||||
├── CURRENT_STATE.md # Layer 1: Live State (changes every session)
|
||||
├── context/ # Layer 2: Structured Knowledge (per milestone)
|
||||
│ ├── ARCHITECTURE.md # System design, workflows, data flow, pipeline
|
||||
│ ├── CONVENTIONS.md # Coding patterns, rules, gotchas
|
||||
│ ├── COMPONENTS.md # File map, extension points, test organization
|
||||
│ ├── TECH_STACK.md # Dependencies, APIs, providers, versions
|
||||
│ └── GLOSSARY.md # Term definitions, acronyms, data classes
|
||||
├── decisions/ # Layer 3: Decisions (append-only ADRs)
|
||||
│ └── NNN-short-name.md
|
||||
└── plans/ # Layer 4: Plans (implementation checklists)
|
||||
└── NNN-plan-name.md
|
||||
```
|
||||
|
||||
Layers 1-2 are what this skill builds and maintains. Layers 3-4 are written by
|
||||
other workflows (architecture-coordinator, planning sessions) and are read-only
|
||||
inputs for this skill.
|
||||
|
||||
## Operational Modes
|
||||
|
||||
Pick the mode that fits the request:
|
||||
|
||||
### Mode 1: Full Build
|
||||
|
||||
Use when: no context files exist, or the user says "rebuild" / "build memory from scratch".
|
||||
|
||||
1. **Audit existing** — read any current `docs/agent/context/*.md` files. Note what exists.
|
||||
2. **Discover sources** — dynamically scan the codebase (see Discovery below).
|
||||
3. **Extract** — populate each context file (see Extraction Rules below).
|
||||
4. **Cross-reference** — verify no contradictions between files.
|
||||
5. **Quality gate** — run every check (see Quality Gate below).
|
||||
6. **Report** — output the build report.
|
||||
|
||||
### Mode 2: Targeted Update
|
||||
|
||||
Use when: specific code changed and the user says "update memory" or similar.
|
||||
|
||||
1. Identify which source files changed (check `git diff`, user description, or recent commits).
|
||||
2. Map changed files to affected context files using the extraction table below.
|
||||
3. Read only the affected sections, update them, leave the rest untouched.
|
||||
4. Update the freshness marker on modified files only.
|
||||
|
||||
### Mode 3: Audit
|
||||
|
||||
Use when: the user says "audit memory" or "verify context files".
|
||||
|
||||
1. For each of the 5 context files, pick 5 factual claims at random.
|
||||
2. Verify each claim against the actual source code.
|
||||
3. Report: claim, source file checked, pass/fail, correction if needed.
|
||||
4. Fix any failures found.
|
||||
|
||||
---
|
||||
|
||||
## Discovery (Step 1)
|
||||
|
||||
Never hardcode file lists. Discover the codebase dynamically:
|
||||
|
||||
```
|
||||
# Find all Python source files
|
||||
find tradingagents/ cli/ -name "*.py" -type f
|
||||
|
||||
# Find config and metadata
|
||||
ls pyproject.toml .env.example tradingagents/default_config.py
|
||||
|
||||
# Find all class definitions
|
||||
grep -rn "^class " tradingagents/ cli/
|
||||
|
||||
# Find all @tool decorated functions
|
||||
grep -rn "@tool" tradingagents/
|
||||
|
||||
# Find state/data classes
|
||||
grep -rn "@dataclass" tradingagents/ cli/
|
||||
```
|
||||
|
||||
### High-Signal Files (read these first)
|
||||
|
||||
| File | Why |
|
||||
|------|-----|
|
||||
| `tradingagents/default_config.py` | All config keys, defaults, env var pattern |
|
||||
| `tradingagents/graph/trading_graph.py` | Trading workflow, agent wiring |
|
||||
| `tradingagents/graph/scanner_graph.py` | Scanner workflow, parallel execution |
|
||||
| `tradingagents/graph/setup.py` | Agent factory creation, LLM tiers |
|
||||
| `tradingagents/agents/utils/tool_runner.py` | Inline tool execution loop |
|
||||
| `cli/main.py` | CLI commands, entry points |
|
||||
| `pyproject.toml` | Dependencies, versions, Python constraint |
|
||||
| `docs/agent/decisions/*.md` | Architectural constraints (binding rules) |
|
||||
|
||||
### Source Priority
|
||||
|
||||
When information conflicts, trust in this order:
|
||||
1. Source code (always wins)
|
||||
2. ADRs in `docs/agent/decisions/`
|
||||
3. Test files
|
||||
4. Git history
|
||||
5. Config files
|
||||
6. README / other docs
|
||||
|
||||
---
|
||||
|
||||
## Extraction Rules (Step 2)
|
||||
|
||||
### CURRENT_STATE.md
|
||||
|
||||
Three sections only. Max 30 lines total.
|
||||
|
||||
```markdown
|
||||
# Current Milestone
|
||||
[One paragraph: what's the active focus and next deliverable]
|
||||
|
||||
# Recent Progress
|
||||
[Bullet list: what shipped recently, merged PRs, key fixes]
|
||||
|
||||
# Active Blockers
|
||||
[Bullet list: what's stuck or fragile, with brief context]
|
||||
```
|
||||
|
||||
Source: `git log --oneline -20`, open PRs, known issues.
|
||||
|
||||
### ARCHITECTURE.md
|
||||
|
||||
System-level design. Someone reading only this file should understand how the
|
||||
system works end-to-end.
|
||||
|
||||
| Section | What to extract | Source |
|
||||
|---------|----------------|--------|
|
||||
| System Description | One paragraph: what the project is, agent count, vendor count, provider count | `setup.py`, `default_config.py` |
|
||||
| 3-Tier LLM System | Table: tier name, config key, default model, purpose | `default_config.py` |
|
||||
| LLM Provider Factory | Table: provider, config value, client class | `setup.py` or wherever `get_llm_client` lives |
|
||||
| Data Vendor Routing | Table: vendor, capabilities, role (primary/fallback) | `dataflows/`, vendor modules |
|
||||
| Trading Pipeline | ASCII diagram: analysts → debate → trader → risk → judge | `trading_graph.py` |
|
||||
| Scanner Pipeline | ASCII diagram: parallel scanners → deep dive → synthesis | `scanner_graph.py` |
|
||||
| Pipeline Bridge | How scanner output feeds into per-ticker analysis | `macro_bridge.py` or pipeline module |
|
||||
| CLI Architecture | Commands, UI components (Rich, MessageBuffer) | `cli/main.py` |
|
||||
| Key Source Files | Table: file path, purpose (10-15 files max) | Discovery step |
|
||||
|
||||
### CONVENTIONS.md
|
||||
|
||||
Rules and patterns. Written as imperatives — "Always...", "Never...", "Use...".
|
||||
Every convention must cite its source file.
|
||||
|
||||
| Section | What to extract |
|
||||
|---------|----------------|
|
||||
| Configuration | Env var override pattern, per-tier overrides, `.env` loading |
|
||||
| Agent Creation | Factory closure pattern `create_X(llm)`, tool binding rules |
|
||||
| Tool Execution | Trading: `ToolNode` in graph. Scanners: `run_tool_loop()`. Constants: `MAX_TOOL_ROUNDS`, `MIN_REPORT_LENGTH` |
|
||||
| Vendor Routing | Fail-fast default (ADR 011), `FALLBACK_ALLOWED` whitelist (list all methods), exception types to catch |
|
||||
| yfinance Gotchas | `top_companies` has ticker as INDEX not column, `Sector.overview` has no perf data, ETF proxies |
|
||||
| LangGraph State | Parallel writes need reducers, `_last_value` reducer, list all state classes |
|
||||
| Threading | Rate limiter: never hold lock during sleep/IO, rate limits per vendor |
|
||||
| Ollama | Never hardcode `localhost:11434`, use configured `base_url` |
|
||||
| CLI Patterns | Typer commands, Rich UI, `MessageBuffer`, `StatsCallbackHandler` |
|
||||
| Pipeline Patterns | `MacroBridge`, `ConvictionLevel`, `extract_json()` |
|
||||
| Testing | pytest commands, markers, mocking patterns (`VENDOR_METHODS` dict patching), env isolation |
|
||||
| Error Handling | Fail-fast by default, exception hierarchies per vendor, `raise from` chaining |
|
||||
|
||||
### COMPONENTS.md
|
||||
|
||||
Concrete inventory. The reader should be able to find any file or class quickly.
|
||||
|
||||
| Section | What to extract |
|
||||
|---------|----------------|
|
||||
| Directory Tree | Run `find` and format as tree. Verify against actual filesystem. |
|
||||
| Class Inventory | Table: class name, file, purpose. Use `grep "^class "` to discover. |
|
||||
| Extension Guides | Step-by-step: how to add a new analyst, scanner, vendor, config key, LLM provider |
|
||||
| CLI Commands | Table: command name, description, entry point |
|
||||
| Test Organization | Table: test file, type (unit/integration), what it covers, markers |
|
||||
|
||||
### TECH_STACK.md
|
||||
|
||||
Dependencies and external services. All version constraints come from `pyproject.toml`.
|
||||
|
||||
| Section | What to extract |
|
||||
|---------|----------------|
|
||||
| Core Dependencies | Table: package, version constraint (from pyproject.toml), purpose |
|
||||
| External APIs | Table: service, auth env var, rate limit, primary use |
|
||||
| LLM Providers | Table: provider, config value, client class, example models |
|
||||
| Python Version | From pyproject.toml `requires-python` |
|
||||
| Dev Tools | pytest version, conda, etc. |
|
||||
|
||||
Do NOT include packages that aren't in `pyproject.toml`. Do NOT list aspirational
|
||||
or unused dependencies.
|
||||
|
||||
### GLOSSARY.md
|
||||
|
||||
Every project-specific term, organized by domain. Each term cites its source file.
|
||||
|
||||
| Domain Section | Terms to include |
|
||||
|---------------|-----------------|
|
||||
| Agents & Workflows | Trading Graph, Scanner Graph, Agent Factory, ToolNode, run_tool_loop, Nudge |
|
||||
| Data Layer | route_to_vendor, VENDOR_METHODS, FALLBACK_ALLOWED, ETF Proxy, etc. |
|
||||
| Configuration | quick_think, mid_think, deep_think, _env(), _env_int() |
|
||||
| Vendor-Specific | Exception types (AlphaVantageError, FinnhubError, etc.) |
|
||||
| State & Data Classes | All @dataclass classes, state types |
|
||||
| Pipeline | MacroBridge, MacroContext, StockCandidate, TickerResult, ConvictionLevel |
|
||||
| CLI | MessageBuffer, StatsCallbackHandler, AnalystType, FIXED_AGENTS |
|
||||
| Constants | All significant constants with actual values and source line |
|
||||
|
||||
---
|
||||
|
||||
## Quality Gate (Step 3)
|
||||
|
||||
Every context file must pass ALL of these before you're done:
|
||||
|
||||
1. **Accurate** — Every statement is verifiable in the current source code. If you wrote
|
||||
"17 agents", count them. If you wrote ">=3.10", check pyproject.toml.
|
||||
2. **Current** — Reflects the latest code on the working branch, not an old snapshot.
|
||||
3. **Complete** — All 8 subsystems covered: agents, dataflows, graphs, pipeline, CLI,
|
||||
LLM clients, config, tests. If a subsystem is missing, the gate fails.
|
||||
4. **Concise** — No information duplicated across context files. Each fact lives in
|
||||
exactly one file.
|
||||
5. **Navigable** — A reader can find any specific fact within 2 scrolls or searches.
|
||||
6. **Quantified** — Constants use actual values from source code (e.g., `MAX_TOOL_ROUNDS=5`),
|
||||
never vague descriptions ("a maximum number of rounds").
|
||||
7. **Cross-referenced** — Every convention cites a source file. Every glossary term
|
||||
links to where it's defined.
|
||||
|
||||
### Mandatory Verification Steps
|
||||
|
||||
These checks catch the most common errors. Run them before declaring the gate passed.
|
||||
|
||||
1. **Dependency verification**: Parse `pyproject.toml` `[project.dependencies]` and
|
||||
`[project.optional-dependencies]`. Only list packages that actually appear there.
|
||||
If a package exists in source imports but not in pyproject.toml, flag it as
|
||||
"undeclared dependency" — do not silently add it to TECH_STACK.
|
||||
|
||||
2. **Model name verification**: Read `default_config.py` and extract the actual model
|
||||
identifiers (e.g., `"gpt-4o-mini"`, not guessed names). Cross-check any model names
|
||||
in ARCHITECTURE.md against what's actually in the config.
|
||||
|
||||
3. **Agent count verification**: Run `grep -rn "def create_" tradingagents/agents/` and
|
||||
count unique agent factory functions. Use the real count, not an estimate.
|
||||
|
||||
4. **ADR cross-reference verification**: Every ADR cited in context files (e.g., "ADR 011")
|
||||
must exist in `docs/agent/decisions/`. Run `ls docs/agent/decisions/` and confirm.
|
||||
|
||||
5. **Class existence verification**: Every class listed in COMPONENTS.md must exist in
|
||||
the codebase. Run `grep -rn "^class ClassName" tradingagents/ cli/` for each one.
|
||||
|
||||
### What NOT to do
|
||||
|
||||
- Do not copy code blocks into docs — reference the file and line instead
|
||||
- Do not describe aspirational or planned features as current facts
|
||||
- Do not use stale information from old branches or outdated READMEs
|
||||
- Do not round numbers — use the exact values from source
|
||||
- Do not skip CLI or pipeline subsystems (common oversight)
|
||||
- Do not list dependencies without version constraints from pyproject.toml
|
||||
- Do not list model names you haven't verified in default_config.py
|
||||
- Do not include packages from imports that aren't declared in pyproject.toml
|
||||
- Do not exceed 200 lines per context file — if you're over, split or trim
|
||||
|
||||
## Freshness Markers (Step 4)
|
||||
|
||||
Every context file starts with:
|
||||
```
|
||||
<!-- Last verified: YYYY-MM-DD -->
|
||||
```
|
||||
Set to today's date when creating or updating the file.
|
||||
|
||||
## Build Report (Step 5)
|
||||
|
||||
After completing any mode, output:
|
||||
|
||||
```
|
||||
## Memory Build Report
|
||||
|
||||
**Mode**: Build | Update | Audit
|
||||
**Date**: YYYY-MM-DD
|
||||
|
||||
### Files
|
||||
| File | Status | Lines |
|
||||
|------|--------|-------|
|
||||
| CURRENT_STATE.md | created/updated/unchanged | N |
|
||||
| context/ARCHITECTURE.md | created/updated/unchanged | N |
|
||||
| ... | ... | ... |
|
||||
|
||||
### Sources Consulted
|
||||
- [list of key files read]
|
||||
|
||||
### Quality Gate
|
||||
| Criterion | Status |
|
||||
|-----------|--------|
|
||||
| Accurate | pass/fail |
|
||||
| Current | pass/fail |
|
||||
| Complete | pass/fail |
|
||||
| Concise | pass/fail |
|
||||
| Navigable | pass/fail |
|
||||
| Quantified | pass/fail |
|
||||
| Cross-referenced | pass/fail |
|
||||
|
||||
### Subsystem Coverage
|
||||
- [x] Agents
|
||||
- [x] Dataflows
|
||||
- [x] Graphs
|
||||
- [x] Pipeline
|
||||
- [x] CLI
|
||||
- [x] LLM Clients
|
||||
- [x] Config
|
||||
- [x] Tests
|
||||
```
|
||||
|
|
@ -0,0 +1,176 @@
|
|||
---
|
||||
name: Memory Reader
|
||||
description: >
|
||||
Reads and applies the project's structured memory system (docs/agent/) at the start
|
||||
of any technical task. Use this skill at the beginning of every new session, when
|
||||
starting a new feature or bug fix, when switching to a different part of the codebase,
|
||||
or when the user says "read memory", "load context", "check decisions", "what's the
|
||||
current state", "read the ADRs", "what are the conventions", or "catch me up".
|
||||
This skill acts as a gatekeeper — it ensures all code changes respect established
|
||||
architecture decisions and current project state. Trigger proactively at session start
|
||||
before writing any code.
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Memory Reader
|
||||
|
||||
Load the project's structured memory before doing any technical work. This skill
|
||||
ensures you understand the current state, architectural constraints, and coding
|
||||
conventions before writing or proposing any code changes.
|
||||
|
||||
## When to Read Memory
|
||||
|
||||
Read memory **before** any of these actions:
|
||||
- Implementing a feature
|
||||
- Fixing a bug
|
||||
- Refactoring code
|
||||
- Adding a new module or agent
|
||||
- Modifying configuration
|
||||
- Changing architecture
|
||||
- Writing or modifying tests
|
||||
|
||||
If `docs/agent/` doesn't exist, skip gracefully and suggest running the memory-builder
|
||||
skill to set it up.
|
||||
|
||||
## Reading Sequence
|
||||
|
||||
Follow this sequence in order. Each step builds on the previous.
|
||||
|
||||
### Step 1: Current State
|
||||
|
||||
Read `docs/agent/CURRENT_STATE.md` and extract:
|
||||
- **Active milestone** — what's the current focus?
|
||||
- **Recent progress** — what just shipped? What PRs merged?
|
||||
- **Blockers** — what's stuck or fragile?
|
||||
|
||||
This tells you what the team is working on right now and what to be careful around.
|
||||
|
||||
### Step 2: Relevant Architecture Decisions
|
||||
|
||||
List all files in `docs/agent/decisions/` and find ADRs relevant to your current task.
|
||||
|
||||
**How to match relevance:**
|
||||
|
||||
1. Extract keywords from the task (e.g., "add a new vendor" → vendor, fallback, routing)
|
||||
2. Match against ADR filenames (e.g., `002-data-vendor-fallback.md`, `011-opt-in-vendor-fallback.md`)
|
||||
3. When uncertain, read the ADR — a false positive costs less than missing a constraint
|
||||
|
||||
**For each relevant ADR, extract:**
|
||||
- `Consequences & Constraints` — treat as **hard rules** (MUST/MUST NOT)
|
||||
- `Actionable Rules` — treat as **implementation requirements**
|
||||
- `Status` — only `accepted` or `active` ADRs are binding
|
||||
|
||||
| Status | Binding? |
|
||||
|--------|----------|
|
||||
| `accepted` / `active` | Yes — all code must comply |
|
||||
| `proposed` | Informational only |
|
||||
| `deprecated` | Ignore |
|
||||
| `superseded` | Follow the superseding ADR instead |
|
||||
| Missing status field | Default to `accepted` (binding) |
|
||||
|
||||
### Step 3: Context Files
|
||||
|
||||
Read the context files relevant to your task. You don't always need all 5 — pick
|
||||
based on what you're doing:
|
||||
|
||||
| If your task involves... | Read these |
|
||||
|--------------------------|------------|
|
||||
| System design, workflows, adding agents | `ARCHITECTURE.md` |
|
||||
| Writing code, patterns, gotchas | `CONVENTIONS.md` |
|
||||
| Finding files, classes, extending the system | `COMPONENTS.md` |
|
||||
| Dependencies, APIs, providers | `TECH_STACK.md` |
|
||||
| Understanding project terminology | `GLOSSARY.md` |
|
||||
| Any significant change | All of them |
|
||||
|
||||
Context files live in `docs/agent/context/`. If the directory doesn't exist, note
|
||||
the absence and proceed without — but flag it to the user.
|
||||
|
||||
### Step 4: Active Plans
|
||||
|
||||
Check `docs/agent/plans/` for any plan related to the current task.
|
||||
|
||||
- If a plan exists, identify the current step and follow it
|
||||
- Do not skip steps without explicit user approval
|
||||
- If no plan exists, proceed but note the absence
|
||||
|
||||
### Step 5: Acknowledge
|
||||
|
||||
Start your first response to any technical task with a brief acknowledgment:
|
||||
|
||||
```
|
||||
I've reviewed the project memory:
|
||||
- **State**: [one-line summary of current milestone]
|
||||
- **ADRs**: [relevant decisions noted, or "none applicable"]
|
||||
- **Context**: [key conventions or constraints for this task]
|
||||
- **Plan**: [current step, or "no active plan"]
|
||||
|
||||
Proceeding with [task description]...
|
||||
```
|
||||
|
||||
If no docs exist:
|
||||
|
||||
```
|
||||
No memory files found in docs/agent/. Proceeding without constraints.
|
||||
Consider running the memory-builder skill to set up the project memory.
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
When a user request contradicts an ADR:
|
||||
|
||||
1. **Stop** — do not write conflicting code
|
||||
2. **Quote** the specific rule, including the file path
|
||||
3. **Present options**:
|
||||
|
||||
```
|
||||
Conflict with `docs/agent/decisions/NNN-name.md`:
|
||||
|
||||
> "[exact quoted rule]"
|
||||
|
||||
Your request to [description] would violate this constraint.
|
||||
|
||||
Options:
|
||||
A) Modify the approach to comply with the ADR
|
||||
B) Update the ADR to allow this exception (I can draft the amendment)
|
||||
C) Proceed with an explicit exception (will be logged)
|
||||
```
|
||||
|
||||
4. **Wait** for the user's decision before proceeding
|
||||
|
||||
## Staleness Detection
|
||||
|
||||
While reading, check for signs that the memory is outdated:
|
||||
|
||||
- Freshness markers (`<!-- Last verified: YYYY-MM-DD -->`) older than 14 days
|
||||
- CURRENT_STATE.md mentions milestones that appear completed in git history
|
||||
- Context files reference files or classes that no longer exist
|
||||
- Dependency versions in TECH_STACK.md don't match pyproject.toml
|
||||
|
||||
If staleness is detected, warn the user:
|
||||
|
||||
```
|
||||
Memory may be stale — [specific issue found]. Consider running the
|
||||
memory-builder skill in update mode to refresh.
|
||||
```
|
||||
|
||||
## Updating State After Work
|
||||
|
||||
After completing a significant task, update `docs/agent/CURRENT_STATE.md`:
|
||||
|
||||
- Add completed work to "Recent Progress"
|
||||
- Remove resolved items from "Active Blockers"
|
||||
- Update the milestone summary if it changed
|
||||
|
||||
This keeps the memory fresh for the next session. Only update CURRENT_STATE.md —
|
||||
the other context files are updated via the memory-builder skill.
|
||||
|
||||
## Graceful Degradation
|
||||
|
||||
| Missing Resource | Action |
|
||||
|------------------|--------|
|
||||
| `docs/agent/` entirely | Proceed without constraints; suggest scaffolding |
|
||||
| `CURRENT_STATE.md` only | Warn, continue to decisions |
|
||||
| `decisions/` empty | Note absence, proceed freely |
|
||||
| `context/` empty | Proceed; suggest running memory-builder |
|
||||
| `plans/` empty | Proceed without plan context |
|
||||
| Individual context file | Note which is missing, use what's available |
|
||||
|
|
@ -223,6 +223,7 @@ reports/
|
|||
results/
|
||||
eval_results/
|
||||
plans/
|
||||
Y/
|
||||
|
||||
# Backup files
|
||||
*.backup
|
||||
|
|
|
|||
Loading…
Reference in New Issue