# Active Backlog

**Last Updated**: 2025-10-04
**Current Version**: v1.6.0 (PUBLISHED) | v1.6.1 (IN PROGRESS - Critical Hotfix)
**Status**: v1.6.0 Released with Agent Discovery Bug → v1.6.1 Hotfix in Progress

---

## 🚨 URGENT: v1.6.1 Hotfix - Agent Discovery

**Priority**: 🔴 CRITICAL
**Status**: ✅ Fix implemented, needs testing and release
**Issue**: v1.6.0 cannot discover specialized agents, falls back to "general-purpose"

### Root Cause
Missing `setting_sources=["project"]` in ClaudeAgentOptions prevented SDK from loading project-level agents.

### Fix Applied
- ✅ Added `setting_sources=["project"]` to chat.py:252
- ⏳ Needs testing with real workflow
- ⏳ Needs PyPI release

### Documentation
- See: `artifacts/backlog/RUNTIME-ISSUES-ANALYSIS.md` (complete issue analysis)
- See: `artifacts/backlog/V1.6.1-RELEASE-PLAN.md` (release plan)

---

## 🎯 Current Focus: v1.6.1 Release (Same-Day Hotfix)

### Phase 2: Parallel Subagents via Prompt Engineering
**Timeline**: 1-2 days
**Priority**: 🟢 HIGH
**Status**: ✅ UNBLOCKED - New strategy identified
**Expected Impact**: 3-4x speed improvement

---

## 💡 CRITICAL BREAKTHROUGH

**Discovery**: From official SDK documentation ([building-agents.md](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)):

> "Claude Agent SDK supports subagents by default. Subagents enable parallelization: you can spin up multiple subagents to work on different tasks simultaneously."

### What This Means

1. **Markdown agents ARE subagents** - The 18 agents in `.claude/agents/` are already subagents
2. **SDK already supports parallel execution** - No code changes needed
3. **Parallelization is automatic** - Claude decides when to parallelize based on task
4. **No programmatic config required** - Just prompt Claude to use multiple agents

### Previous Misunderstanding (v1.5.5-v1.5.10)

We thought we needed:
- ❌ Programmatic `agents` parameter (broken in Python SDK)
- ❌ `AgentDefinition` dataclass instances
- ❌ Code changes to enable parallelization

### New Understanding (v1.5.11+)

We actually have:
- ✅ 18 markdown subagents already bundled
- ✅ SDK auto-loads from `add_dirs=[Path(".claude")]`
- ✅ Parallel execution capability built-in
- ✅ Just need proper prompts to trigger parallel use

---

## 📋 Phase 2: New Implementation Strategy

### Objectives

- [ ] Update investment command prompts to request parallel subagent use
- [ ] Test parallel execution with `/invest:research-stock` command
- [ ] Measure actual speedup achieved
- [ ] Verify cache effectiveness (maintain ~70% hit rate)
- [ ] Document which agents run in parallel

### Implementation Steps

#### Step 1: Update Command Prompts (30 min)
Update `.claude/commands/invest/*.md` files to explicitly request parallel agent coordination:

**Example for research-stock.md:**
```markdown
Coordinate these specialist agents to work IN PARALLEL:

1. **fundamental-analyst** - Analyze company financials, fundamentals, valuations
2. **technical-analyst** - Analyze price patterns, technical indicators, trends
3. **news-analyst** - Analyze news sentiment, market narrative, catalysts

CRITICAL: Launch all agents simultaneously, wait for completion, then synthesize results.
```

#### Step 2: Test Parallel Execution (1 hour)
```bash
# Run workflow with timing
time navam chat --prompt "/invest:research-stock AAPL"

# Expected: 2-3 minutes (vs 8+ minutes sequential)
# Watch for parallel agent activity in logs
```

#### Step 3: Measure & Validate (30 min)
- Workflow time: Target <3 minutes
- Cache hit rate: Maintain ~70%
- Agent coordination: Verify 3 agents used
- Report quality: No regression

### Success Metrics

| Metric | Before (v1.5.11) | Target (v1.6.0) | Status |
|--------|------------------|-----------------|--------|
| Workflow Time | 8-9 min sequential | 2-3 min parallel | ⏳ |
| Cache Hit Rate | 70% | 70% | ⏳ |
| Agents Used | 1 main agent | 3+ subagents | ⏳ |
| Cost per Query | $0.40 | $0.30 | ⏳ |

---

## 📚 Technical Architecture

### Current State (v1.5.11)

```python
# chat.py configuration
self.claude_options = ClaudeAgentOptions(
    add_dirs=[Path(".claude")],      # ✅ Loads subagents from .claude/agents/
    setting_sources=["project"],     # ✅ Enables project-level agents
    hooks={                          # ✅ Cache hooks working (70% hit rate)
        'pre_tool_use': self._pre_tool_use_hook,
        'post_tool_use': self._post_tool_use_hook
    },
    # No 'agents' parameter needed - markdown files work automatically!
)
```

**Available Subagents** (18 total in `src/navam/.claude/agents/`):
- fundamental-analyst.md
- technical-analyst.md
- news-analyst.md
- earnings-whisperer.md
- macro-lens-strategist.md
- ... and 13 more

### How Parallelization Works

From SDK documentation:

1. **Main agent receives task**: "Research AAPL using fundamental, technical, news analysts"
2. **SDK launches subagents**: Each agent gets isolated context, specific tools
3. **Parallel execution**: Agents work simultaneously on their subtasks
4. **Result synthesis**: Only relevant info sent back to main agent
5. **Context efficiency**: Subagents don't pollute main agent's context

### Why This Approach Works

**Built-in SDK Features:**
- ✅ Markdown agents = subagents (automatic)
- ✅ Parallel execution (SDK native capability)
- ✅ Context isolation (each agent has own window)
- ✅ Result aggregation (SDK handles)

**No Code Changes Required:**
- ❌ No `agents` parameter needed
- ❌ No `AgentDefinition` dataclass
- ❌ No SDK option modifications

**Just Prompt Engineering:**
- ✅ Update command prompts
- ✅ Request parallel coordination
- ✅ Specify which agents to use

---

## 🔄 Upcoming Phases

### Phase 3: Enhanced Cost Tracking (v1.6.1)
**Timeline**: 1 day
**Priority**: 🟡 MEDIUM
**Expected Impact**: Better visibility into spending

**Tasks:**
- [ ] Add per-agent cost tracking
- [ ] Show cache savings breakdown
- [ ] Display parallel execution metrics
- [ ] Update `/perf` command with new data

### Phase 4: Streaming Reports (v1.7.0)
**Timeline**: 2-3 days
**Priority**: 🟢 MEDIUM
**Expected Impact**: 5x faster perceived speed

**Tasks:**
- [ ] Stream results as each subagent completes
- [ ] Display progressive report sections
- [ ] Update progress indicators
- [ ] Test user experience

---

## 🔍 Issues Under Investigation

### File Write Operations Slow (v1.4.7)
**Severity**: Medium
**Impact**: Report generation workflows
**Status**: 🔍 INVESTIGATING

**Problem:**
- Write to `/tmp/` directory: instant ✅
- Write to `reports/` directory: 2m 45s delay ❌
- Inconsistent behavior between different paths

**Next Steps:**
- [ ] Run production workflow with timing logs
- [ ] Profile SDK Write tool internals
- [ ] Check if permission handler causes delay

**Reference**: See archive-002.md for historical context

---

## 📖 Reference Documents

### Core Documentation
- **Python SDK API**: `artifacts/refer/claude-agent-sdk/PYTHON-SDK-API-REFERENCE.md`
- **Building Agents**: `artifacts/refer/claude-agent-sdk/building-agents.md` ⭐ **KEY INSIGHTS**
- **Migration Guide**: `artifacts/refer/claude-agent-sdk/MIGRATION-GUIDE.md`
- **Critical Insights**: `artifacts/refer/claude-agent-sdk/CRITICAL-INSIGHTS-FOR-NAVAM.md`

### Known Issues
- **Programmatic Agents**: `artifacts/refer/claude-agent-sdk/PROGRAMMATIC-AGENTS-NOT-WORKING.md`
- **AgentDefinition Details**: `artifacts/refer/claude-agent-sdk/AGENTS-MUST-BE-DATACLASSES.md`

### Completed Work
- **Phase 0**: SDK Migration (archive-002.md)
- **Phase 1**: Hook-Based Caching (archive-002.md)
- **v1.5.3**: Package structure fix (archive-002.md)
- **v1.5.11**: Stable release, programmatic agents disabled

---

## 🎯 Overall Progress

**Completed:**
- ✅ Phase 0: SDK Migration (v1.5.0-alpha)
- ✅ Phase 1: Hook-Based Caching (v1.5.4)
- ✅ v1.5.3: Package structure fix (consistent `.claude/` layout)
- ✅ v1.5.11: Stable release with markdown subagents

**Current:**
- 🔄 Phase 2: Parallel Subagents - Ready to execute (prompt engineering approach)

**Next:**
- ⏳ Phase 3: Enhanced Cost Tracking
- ⏳ Phase 4: Streaming Reports

---

## 💡 Key Metrics (Current vs Target)

| Metric | v1.4.8 (Before) | v1.5.11 (Current) | v1.6.0 (Target) | Improvement |
|--------|-----------------|-------------------|-----------------|-------------|
| Workflow Time | 8.3 min | ~3-4 min (est) | 2-3 min | 60-75% faster |
| API Calls Saved | 0% | 70% | 70% | ✅ Achieved |
| Cost per Query | $1.32 | $0.40 | $0.30 | 70%+ cheaper |
| Cache Hit Rate | 0% | 70% | 70% | ✅ Achieved |
| Parallel Agents | No | Available | Yes (active) | 🔄 In Progress |
| User Feedback | Blocking | Blocking | Progressive | Next Phase |

---

## 🚨 Critical Workflow

**Before Building Package:**
```bash
# 1. ALWAYS sync development files to package
uv run python src/navam/sync.py

# 2. Verify sync succeeded
ls -la src/navam/.claude/agents/          # Should show 18 agents
ls -la src/navam/.claude/commands/invest/ # Should show 8 commands

# 3. Build package
uv run python -m build
```

**Why This Matters:**
- Package uses **consistent `.claude/` structure** for all resources
- Agents: `src/navam/.claude/agents/` (18 subagent files)
- Commands: `src/navam/.claude/commands/invest/` (8 workflow files)
- Development keeps everything in `.claude/` for Claude Code integration
- Sync script bridges the two without disturbing development setup
- **Without sync, package fails with "agents not found" errors**

---

## 📋 What Changed from Previous Strategy

### Old Approach (v1.5.5-v1.5.10) ❌
- Tried programmatic `agents` parameter
- Created `agent_configs.py` with `AgentDefinition` instances
- Hit Python SDK bug: `'method' object is not iterable`
- Rolled back in v1.5.11

### New Approach (v1.5.11+) ✅
- Use existing markdown agents (already subagents)
- Rely on SDK's built-in parallel execution
- Update command prompts to request parallel coordination
- No code changes to SDK options needed

### Key Insight
> "We don't need to fix the SDK - we just need to use it correctly"

The SDK already does what we need. The `agents` parameter is for programmatic configuration (broken in Python), but markdown file agents work perfectly and ARE subagents with parallel execution capability.

---

## 🚀 Next Actions

**Immediate (Today):**
1. ✅ Backlog consolidation (DONE)
2. ⏳ Update Phase 2 strategy documentation
3. ⏳ Review command prompts for parallel coordination
4. ⏳ Plan Phase 2 testing approach

**This Week:**
1. Execute Phase 2 (prompt engineering)
2. Test parallel subagent execution
3. Measure speedup vs baseline
4. Release v1.6.0 if successful

**Next Week:**
1. Phase 3: Enhanced cost tracking
2. Monitor production performance
3. Gather user feedback on speed

---

**Status**: Active development, clear path forward ✅
