charieswei
/
TradingAgents
mirror of https://github.com/TauricResearch/TradingAgents.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

skills

This commit is contained in:
Ahmet Guzererler 2026-03-19 10:32:29 +01:00
parent a90f14c086
commit 97ab49bb99
6 changed files with 828 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
.DS_Store vendored Normal file
View File

Binary file not shown.

309
.claude/agents/architect.md Normal file
View File

@ -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 |

22
.claude/commands/architect.md Normal file
View File

@ -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

320
.claude/skills/skills/memory-builder/SKILL.md Normal file
View File

@ -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
```

176
.claude/skills/skills/memory-reader/SKILL.md Normal file
View File

@ -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 |

1
.gitignore vendored
View File

@ -223,6 +223,7 @@ reports/
results/ results/
eval_results/ eval_results/
plans/ plans/
Y/
# Backup files # Backup files
*.backup *.backup