Dev

.ai-context/architecture-decisions.md

@@ -0,0 +1,83 @@
+# Architecture Decisions
+
+> Records counter-intuitive design decisions that AI agents cannot infer from code.
+> Only add entries for decisions that would surprise someone reading the code.
+
+---
+
+## ADR-001: LoopAgent max_iterations=1
+
+**Decision**: All Actor-Critic loops use `max_iterations=1`
+
+**Reason**: SequentialAgent has a bug where `exit_loop()` terminates the entire chain, not just the loop. Using `max_iterations=1` lets LoopAgent complete naturally.
+
+**Impact**: All critical stages (PRD, Design, Plan, Coding)
+
+**Do not**: Change this parameter or migrate to SequentialAgent without testing
+
+---
+
+## ADR-002: JSON Storage over SQLite
+
+**Decision**: Use JSON files for persistence instead of SQLite
+
+**Reason**: Simpler debugging, easy to inspect/edit, no external dependencies. Data volume is small and there's no concurrent access requirement.
+
+**Impact**: All persistence layer, no migrations needed
+
+**Limitation**: Not suitable for large-scale concurrent scenarios
+
+---
+
+## ADR-003: Coding Stage has 5 Iterations
+
+**Decision**: Coding Actor-Critic loop allows `max_iterations=5` while others only 1
+
+**Reason**: Code often needs iterative refinement based on test results. Other stages typically complete in one pass.
+
+**Impact**: CodingStage, coding_loop agent
+
+---
+
+## ADR-004: Two-Step Knowledge Promotion
+
+**Decision**: Insights → Decisions requires two separate tools (SaveInsightTool + PromoteToDecisionTool)
+
+**Reason**: Not all insights should become decisions. Human review at promotion step ensures quality.
+
+**Impact**: Memory tools, knowledge workflow
+
+---
+
+## ADR-005: GotoStage Only Goes Backward
+
+**Decision**: GotoStageTool can only jump to earlier stages, never forward
+
+**Reason**: Skipping stages would miss required artifacts. Re-executing earlier stages is safe.
+
+**Impact**: Pipeline control flow, PM Agent navigation
+
+---
+
+## ADR-006: HITL Timeout Default Pass
+
+**Decision**: If HITL confirmation times out, default action is "Pass" (continue)
+
+**Reason**: Better to proceed than to block indefinitely. User can always re-run or use PM Agent to navigate back.
+
+**Impact**: Stage execution, GUI timeout handling
+
+---
+
+## Adding New ADRs
+
+When making a design decision that:
+- Goes against common patterns
+- Has non-obvious rationale
+- Would confuse someone reading the code later
+
+Add an entry with:
+- Clear decision statement
+- The "why" (most important)
+- Impact scope
+- Any "do not" warnings

.ai-context/core/constraints.md

@@ -0,0 +1,53 @@
+# Constraints & Boundaries
+
+## Security Constraints
+
+| Constraint | Rule |
+|------------|------|
+| Path Validation | All file ops within workspace |
+| Blocked Commands | rm -rf, sudo, chmod 777, mkfs, dd |
+| Allowed Commands | cargo, npm, pip, bun, yarn, python, node, git (read-only) |
+
+## Rate Limiting
+
+| Resource | Limit |
+|----------|-------|
+| LLM API | 30 req/min, concurrency=1 |
+| Retry | 3 attempts with backoff |
+
+## HITL Gates
+
+- Critical stages (prd, design, plan, coding): require confirmation
+- Non-critical (idea, check, delivery): auto-proceed
+- Max feedback loops: 5 per stage
+
+| Action | Behavior |
+|--------|----------|
+| Pass | Continue |
+| Feedback | Re-execute stage |
+| Cancel | Pause iteration |
+
+## Tool Limits
+
+| Constraint | Value |
+|------------|-------|
+| Max file size | 1MB |
+| Max files per list | 100 |
+
+## Error Handling
+
+| Type | Behavior |
+|------|----------|
+| LLM timeout | Retry with backoff |
+| Tool failure | Retry up to 3 times |
+| Invalid config | Halt, require fix |
+| Security violation | Halt, log |
+
+## Interaction Layer
+
+| Backend | Location | Use Case |
+|---------|----------|----------|
+| CliBackend | `interaction/cli.rs` | Terminal + dialoguer |
+| TauriBackend | `interaction/tauri.rs` | Event-driven IPC |
+
+HITL Flow: `request_input([Pass, Feedback, Cancel])` → wait for response

.ai-context/core/modules.map

@@ -0,0 +1,123 @@
+# Module Dependency Map
+# Purpose: Quick navigation for AI agents to locate code and understand relationships
+# Note: For detailed function signatures, grep the code directly
+
+## ARCHITECTURE LAYERS
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    PRESENTATION LAYER                            │
+│  ┌─────────────────┐         ┌─────────────────────────────┐    │
+│  │   cowork-cli    │         │       cowork-gui            │    │
+│  │   (clap CLI)    │         │  (Tauri + React + Ant D)    │    │
+│  └────────┬────────┘         └──────────────┬──────────────┘    │
+└───────────┼──────────────────────────────────┼──────────────────┘
+            │                                  │
+            ▼                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│                    APPLICATION LAYER                              │
+│   ┌─────────────────────────────────────────────────────────┐    │
+│   │              InteractiveBackend Trait                    │    │
+│   └─────────────────────────────────────────────────────────┘    │
+│                              ▼                                    │
+│   ┌─────────────────────────────────────────────────────────┐    │
+│   │                  IterationExecutor                       │    │
+│   └─────────────────────────────────────────────────────────┘    │
+└───────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌───────────────────────────────────────────────────────────────────┐
+│                    DOMAIN LAYER (cowork-core)                     │
+│   Project (Aggregate) │ Iteration (Entity) │ ProjectMemory       │
+│   Stage Trait → [Idea, PRD, Design, Plan, Coding, Check, Delivery]│
+└───────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌───────────────────────────────────────────────────────────────────┐
+│                    INFRASTRUCTURE LAYER                           │
+│   LLM Client │ Stores (JSON) │ Tools (30+) │ ACP │ Skills        │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+## MODULE DEPENDENCY FLOW
+
+```
+CLI/GUI → InteractiveBackend → IterationExecutor → Pipeline → Stages → Agents → Tools → LLM/Persistence
+```
+
+## KEY TRAITS
+
+| Trait | Location | Purpose |
+|-------|----------|---------|
+| `InteractiveBackend` | `interaction/mod.rs` | CLI/GUI abstraction |
+| `Stage` | `pipeline/mod.rs` | Stage execution behavior |
+| `Tool` | adk-rust | Tool execution interface |
+
+## CORE FLOWS
+
+### Genesis Iteration
+```
+create_genesis_iteration() → execute() → stages[idea→delivery] → generate_knowledge()
+```
+
+### Actor-Critic Loop (critical stages)
+```
+Actor generates artifact → Critic validates → HITL confirmation → [Pass|Feedback|Cancel]
+```
+
+### Evolution Iteration
+```
+create_evolution_iteration() → prepare_workspace(inheritance) → inject_knowledge() → stages
+```
+
+## MODULE FILES REFERENCE
+
+### Pipeline Module
+`crates/cowork-core/src/pipeline/`
+- `mod.rs` - Stage trait, stage factory
+- `executor/mod.rs` - IterationExecutor (main orchestrator)
+- `executor/interaction_ext.rs` - HITL flow
+- `stages/*.rs` - Individual stage implementations
+
+### Domain Module
+`crates/cowork-core/src/domain/`
+- `project.rs` - Project, ProjectMetadata
+- `iteration.rs` - Iteration, Artifacts, InheritanceMode
+- `memory.rs` - ProjectMemory, IterationKnowledge
+
+### Tools Module
+`crates/cowork-core/src/tools/`
+- `file_tools.rs` - ReadFile, WriteFile, ListFiles
+- `data_tools.rs` - Requirement/Feature/Task CRUD
+- `hitl_tools.rs` - Review, Feedback
+- `memory_tools.rs` - Query, Save, Promote
+- `artifact_tools.rs` - Save stage artifacts
+- `pm_tools.rs` - PM Agent tools
+
+### Persistence Module
+`crates/cowork-core/src/persistence/`
+- `project_store.rs` - ProjectStore
+- `iteration_store.rs` - IterationStore
+- `memory_store.rs` - MemoryStore
+
+### Agents Module
+`crates/cowork-core/src/agents/`
+- `mod.rs` - All agent builders
+- `external_coding_agent.rs` - ACP integration
+
+### Instructions Module
+`crates/cowork-core/src/instructions/`
+- `*.rs` - Prompts for each stage
+
+## QUICK NAVIGATION BY TASK
+
+| Task | Location |
+|------|----------|
+| Modify pipeline execution | `pipeline/executor/mod.rs` |
+| Add new stage | `pipeline/stages/` + register in `mod.rs` |
+| Add new tool | `tools/` + re-export in `mod.rs` |
+| Modify HITL | `interaction/mod.rs` |
+| Add agent instruction | `instructions/` |
+| Modify storage | `persistence/` + `domain/` |
+| Add CLI command | `cowork-cli/src/commands/` |
+| Modify GUI | `cowork-gui/src/` (frontend) or `src-tauri/` (backend) |

.ai-context/domains/domain-logic.md

@@ -0,0 +1,51 @@
+# Domain Logic
+
+## Core Entities
+
+| Entity | Location | Purpose |
+|--------|----------|---------|
+| Project | `domain/project.rs` | Aggregate root, contains Iterations |
+| Iteration | `domain/iteration.rs` | Single development cycle |
+| ProjectMemory | `domain/memory.rs` | Cross-iteration knowledge |
+| IterationKnowledge | `domain/memory.rs` | Single iteration learnings |
+
+## Relationships
+
+```
+Project 1:N Iteration
+Project 1:1 ProjectMemory
+Iteration 1:1 IterationKnowledge
+```
+
+## Iteration Lifecycle
+
+```
+Draft → Running → [Paused] → Completed | Failed
+```
+
+| Status | Operations |
+|--------|------------|
+| Draft | start, delete |
+| Running | pause |
+| Paused | continue, delete |
+| Completed | create_evolution |
+| Failed | retry, delete |
+
+## Iteration Types
+
+| Type | Description |
+|------|-------------|
+| Genesis | Fresh start |
+| Evolution | Based on previous iteration |
+
+## Knowledge Types
+
+| Type | Scope |
+|------|-------|
+| Decision | Project-level |
+| Pattern | Project-level |
+| Issue | Iteration → Project |
+| Learning | Iteration-level |
+
+---
+**Note**: For struct fields, read `domain/*.rs` directly.

.ai-context/domains/pipeline.md

@@ -0,0 +1,48 @@
+# Pipeline & Agents Domain
+
+## 7-Stage Workflow
+
+| Stage | HITL | Pattern | Output |
+|-------|------|---------|--------|
+| Idea | No | Simple | idea.md |
+| PRD | Yes | Actor-Critic | prd.md |
+| Design | Yes | Actor-Critic | design.md |
+| Plan | Yes | Actor-Critic | plan.md |
+| Coding | Yes | Actor-Critic | workspace/ |
+| Check | No | Simple | check_report.md |
+| Delivery | No | Simple | delivery_report.md |
+
+## Execution Flow
+
+```
+prepare_workspace() → stages[idea→delivery] → generate_knowledge()
+                              ↓
+                    HITL gate (critical stages)
+```
+
+## Actor-Critic Pattern
+
+```
+Actor generates → Critic validates → HITL confirms → [Pass|Feedback loop]
+```
+
+**Critical**: LoopAgent uses `max_iterations=1` (see ADR-001)
+
+## Agent Types
+
+| Type | Stages | Pattern |
+|------|--------|---------|
+| Simple | Idea, Check, Delivery | Single LlmAgent |
+| Actor-Critic | PRD, Design, Plan, Coding | LoopAgent |
+| PM Agent | Post-Delivery | Interactive |
+
+## Code Locations
+
+| Component | Location |
+|-----------|----------|
+| Stage trait | `pipeline/mod.rs` |
+| Executor | `pipeline/executor/mod.rs` |
+| Stages | `pipeline/stages/*.rs` |
+| Agent builders | `agents/mod.rs` |
+| Instructions | `instructions/*.rs` |
+| External agent | `agents/external_coding_agent.rs` |

.ai-context/domains/tools.md

@@ -0,0 +1,28 @@
+# Tools Domain
+
+## Tool Categories
+
+| Category | File | Key Tools |
+|----------|------|-----------|
+| File | `file_tools.rs` | ReadFile, WriteFile, ListFiles |
+| Data | `data_tools.rs` | CreateRequirement, AddFeature, GetRequirements, CreateTask |
+| HITL | `hitl_tools.rs` | ReviewWithFeedback, ProvideFeedback |
+| Memory | `memory_tools.rs` | QueryMemory, SaveInsight, PromoteToDecision |
+| Artifact | `artifact_tools.rs` | SaveIdea, SavePrdDoc, SaveDesignDoc |
+| Load | `load_artifacts.rs` | LoadIdea, LoadPrdDoc, LoadFeedbackHistory |
+| Control | `control_tools.rs`, `goto_stage_tool.rs` | GotoStage |
+| Validation | `validation_tools.rs` | CheckFeatureCoverage, CheckTaskDependencies |
+| Test/Lint | `test_lint_tools.rs` | RunCommand, CheckTests, CheckLint |
+| Knowledge | `knowledge_tools.rs` | LoadBaseKnowledge, SaveKnowledgeSnapshot |
+| PM | `pm_tools.rs` | PMGotoStage, PMCreateIteration, PMRespond |
+| Deploy | `deployment_tools.rs` | CopyWorkspaceToProject |
+| Import | `legacy_project_analyzer_tools.rs` | ImportProject |
+
+## Security
+
+- All file ops validated within workspace
+- Dangerous commands blocked
+
+## Location
+
+`crates/cowork-core/src/tools/`