Skip to content

docs: align planning/setup/API references with current behavior #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
cursor wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: align planning/setup/API references with current behavior #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/SYSTEM_ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
document_id: doc.system-architecture
last_verified: 2026-03-06
last_verified: 2026-03-23
tokens_estimate: 950
tags:
- architecture
Expand Down Expand Up @@ -106,7 +106,7 @@ Full schema details: [data-contracts-reference.md](domains/data-contracts-refere
## Data Flow (Summaries)

### Planning
`User chat → Anthropic streaming API → stream-action-parser → PlanningAction[] → validate → apply → SQLite`
`User chat → planning SDK query()/stream wrapper → stream-action-parser → PlanningAction[] → validate → apply → SQLite`

Detail: [planning-reference.md](domains/planning-reference.md)

Expand Down Expand Up @@ -138,12 +138,12 @@ Two distinct connection patterns exist.

| Concern | Planning LLM | Build Agent |
|---------|-------------|-------------|
| Auth | `ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY` |
| SDK | `@anthropic-ai/sdk` (Messages API) | `@anthropic-ai/claude-agent-sdk` |
| Call style | `messages.create` / `messages.stream` | `query()` — async iterator |
| Streaming | Optional (non-streaming for simple calls, streaming for chat) | Always streaming (`for await` over messages) |
| Tools | None (text output only) | Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch |
| CWD | N/A | `worktree_path` (repo clone) |
| Auth | `ANTHROPIC_API_KEY` (env/config) or Claude CLI credential (`~/.claude/settings.json`) | `ANTHROPIC_API_KEY` (env/config) |
| SDK | `@anthropic-ai/claude-agent-sdk` via planning wrapper | `@anthropic-ai/claude-agent-sdk` |
| Call style | `query()` wrapper (non-streaming and streaming paths) | `query()` — async iterator |
| Streaming | Optional (chat stream uses streaming path) | Always streaming (`for await` over messages) |
| Tools | `WebSearch` always; `Read/Glob/Grep` when repo clone (`cwd`) is available | Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch |
| CWD | Optional clone path when repo connected | `worktree_path` (repo clone) |
| Lifecycle | Request-response per chat turn | Fire-and-forget; result via in-process webhook callback |
| Model | `claude-haiku-4-5-20251001` (configurable) | `claude-sonnet-4-5-20250929` (configurable) |

Expand Down
53 changes: 41 additions & 12 deletions docs/domains/planning-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
document_id: doc.planning
last_verified: 2026-03-06
last_verified: 2026-03-23
tokens_estimate: 750
tags:
- planning
Expand Down Expand Up @@ -41,28 +41,55 @@ ttl_expires_on: null
| scaffold | Map empty or no workflows | updateProject + createWorkflow only |
| populate | Workflows exist, activities/cards sparse | createActivity, createStep, createCard |
| full | Map has structure | All action types; refinements, links, planned files |
| finalize | Map fully planned; user triggers | createContextArtifact (project docs + card e2e tests) |
| finalize | User triggers approval/finalize | createContextArtifact (project docs, scaffold docs, and card e2e tests) |

Mode selected by `lib/llm/planning-prompt.ts` based on map state.

### Flow
```
User message → POST /chat/stream
→ buildPlanningSystemPrompt() | buildScaffoldSystemPrompt() | buildPopulateSystemPrompt() | buildFinalizeSystemPrompt()
→ Claude API (streaming)
→ buildScaffoldSystemPrompt() | buildPlanningSystemPrompt() | finalize prompts
→ claude-client -> planning-sdk-runner (Agent SDK query())
→ stream-action-parser (parse JSON blocks)
→ PlanningAction[] emitted
→ POST /actions (validate + apply)
→ validatePlanningOutput() + pipelineApply() inside chat route
```

Planning uses read-only tools:
- Always: `WebSearch`
- When repo is connected and cloned: `Read`, `Glob`, `Grep`, `WebSearch` (cwd set to clone path)

Auth resolution for planning:
1. `ANTHROPIC_API_KEY` from env
2. `ANTHROPIC_API_KEY` from `~/.dossier/config`
3. Claude CLI settings (`~/.claude/settings.json`, respecting `CLAUDE_CONFIG_DIR`):
- `env.ANTHROPIC_API_KEY`, or
- `env.ANTHROPIC_AUTH_TOKEN` (also mapped to `CLAUDE_CODE_OAUTH_TOKEN`)

### Per-Card Finalize Flow
```
User clicks "Finalize" on card → POST /cards/[cardId]/finalize
→ Assemble: project-wide docs + card context + e2e tests
→ Return finalization package for review
→ User edits (optional)
→ POST /cards/[cardId]/finalize/confirm
→ Set card.finalized_at → card is build-ready
→ Validate prerequisites:
project.finalized_at exists
card has requirements
card has planned files
card not already finalized
→ Link project docs to card (doc/spec/design)
→ Generate required test artifact + optional card-specific docs
→ Set card.finalized_at
→ Best-effort memory ingestion for card context
```

### Project Finalize Flow (chat mode=finalize)
```
POST /chat or /chat/stream with mode=finalize
→ runFinalizeMultiStep() executes FINALIZE_DOC_SPECS in parallel
→ each doc emits createContextArtifact
→ failure if any required doc missing
→ parse root folders from architectural-summary
→ ensure clone and create root folders + scaffold files in base branch
→ push base branch
→ set project.finalized_at
```

### Key Files
Expand All @@ -71,8 +98,10 @@ User clicks "Finalize" on card → POST /cards/[cardId]/finalize
| `lib/llm/planning-prompt.ts` | System prompts; mode selection |
| `lib/llm/stream-action-parser.ts` | Parse streaming JSON → actions |
| `lib/llm/build-preview-response.ts` | Preview response before apply |
| `lib/llm/claude-client.ts` | Planning LLM client (Messages API) |
| `lib/llm/planning-credential.ts` | Resolves ANTHROPIC_API_KEY from env or ~/.dossier/config |
| `lib/llm/claude-client.ts` | Planning LLM client; auth routing + timeouts |
| `lib/llm/planning-sdk-runner.ts` | Agent SDK query wrapper for planning (final result only) |
| `lib/llm/planning-credential.ts` | Resolves env/config/CLI credentials |
| `lib/llm/run-finalize-multistep.ts` | Project finalize doc generation (parallel sub-steps) |
| `app/api/projects/[id]/chat/route.ts` | Non-streaming chat |
| `app/api/projects/[id]/chat/stream/route.ts` | Streaming chat (scaffold, populate, finalize) |
| `app/api/projects/[id]/cards/[cardId]/finalize/route.ts` | Per-card finalize endpoint |
Expand Down
Loading