diff --git a/design/note/.gitkeep b/design/note/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/note-agent-harness-references.md b/design/note/note-agent-harness-references.md
similarity index 100%
rename from docs/note-agent-harness-references.md
rename to design/note/note-agent-harness-references.md
diff --git a/docs/note-agent-runtime-design.md b/design/note/note-agent-runtime-design.md
similarity index 100%
rename from docs/note-agent-runtime-design.md
rename to design/note/note-agent-runtime-design.md
diff --git a/docs/note-context-switch-design.md b/design/note/note-context-switch-design.md
similarity index 100%
rename from docs/note-context-switch-design.md
rename to design/note/note-context-switch-design.md
diff --git a/docs/note-knowledge-graph-design.md b/design/note/note-knowledge-graph-design.md
similarity index 100%
rename from docs/note-knowledge-graph-design.md
rename to design/note/note-knowledge-graph-design.md
diff --git a/docs/note-langchain-langgraph.md b/design/note/note-langchain-langgraph.md
similarity index 100%
rename from docs/note-langchain-langgraph.md
rename to design/note/note-langchain-langgraph.md
diff --git a/docs/note-opencode-agent-switching.md b/design/note/note-opencode-agent-switching.md
similarity index 100%
rename from docs/note-opencode-agent-switching.md
rename to design/note/note-opencode-agent-switching.md
diff --git a/docs/note-opencode-subagent-dispatch.md b/design/note/note-opencode-subagent-dispatch.md
similarity index 100%
rename from docs/note-opencode-subagent-dispatch.md
rename to design/note/note-opencode-subagent-dispatch.md
diff --git a/docs/1-llm-types-design.md b/design/pdd/1-llm-types-design.md
similarity index 100%
rename from docs/1-llm-types-design.md
rename to design/pdd/1-llm-types-design.md
diff --git a/docs/10-llm-provider-refinement.md b/design/pdd/10-llm-provider-refinement.md
similarity index 100%
rename from docs/10-llm-provider-refinement.md
rename to design/pdd/10-llm-provider-refinement.md
diff --git a/docs/10a-phase0-types-and-trait.md b/design/pdd/10a-phase0-types-and-trait.md
similarity index 100%
rename from docs/10a-phase0-types-and-trait.md
rename to design/pdd/10a-phase0-types-and-trait.md
diff --git a/docs/10b-phase1-provider-adaptation.md b/design/pdd/10b-phase1-provider-adaptation.md
similarity index 100%
rename from docs/10b-phase1-provider-adaptation.md
rename to design/pdd/10b-phase1-provider-adaptation.md
diff --git a/docs/10c-phase2-llm-cycle-simplify.md b/design/pdd/10c-phase2-llm-cycle-simplify.md
similarity index 100%
rename from docs/10c-phase2-llm-cycle-simplify.md
rename to design/pdd/10c-phase2-llm-cycle-simplify.md
diff --git a/docs/11-v0.1-release-plan.md b/design/pdd/11-v0.1-release-plan.md
similarity index 100%
rename from docs/11-v0.1-release-plan.md
rename to design/pdd/11-v0.1-release-plan.md
diff --git a/docs/12-phase5-warmup-implementation.md b/design/pdd/12-phase5-warmup-implementation.md
similarity index 100%
rename from docs/12-phase5-warmup-implementation.md
rename to design/pdd/12-phase5-warmup-implementation.md
diff --git a/docs/13-phase6-tooldef-ir.md b/design/pdd/13-phase6-tooldef-ir.md
similarity index 100%
rename from docs/13-phase6-tooldef-ir.md
rename to design/pdd/13-phase6-tooldef-ir.md
diff --git a/docs/14-phase7-sqlite-store.md b/design/pdd/14-phase7-sqlite-store.md
similarity index 100%
rename from docs/14-phase7-sqlite-store.md
rename to design/pdd/14-phase7-sqlite-store.md
diff --git a/docs/15-phase8-mvp-integration.md b/design/pdd/15-phase8-mvp-integration.md
similarity index 100%
rename from docs/15-phase8-mvp-integration.md
rename to design/pdd/15-phase8-mvp-integration.md
diff --git a/docs/16-phase9-streaming-experience.md b/design/pdd/16-phase9-streaming-experience.md
similarity index 100%
rename from docs/16-phase9-streaming-experience.md
rename to design/pdd/16-phase9-streaming-experience.md
diff --git a/docs/17-phase10-contextslot.md b/design/pdd/17-phase10-contextslot.md
similarity index 100%
rename from docs/17-phase10-contextslot.md
rename to design/pdd/17-phase10-contextslot.md
diff --git a/docs/18-phase11-testing-and-retrieval.md b/design/pdd/18-phase11-testing-and-retrieval.md
similarity index 100%
rename from docs/18-phase11-testing-and-retrieval.md
rename to design/pdd/18-phase11-testing-and-retrieval.md
diff --git a/docs/19-phase13-cleanup-and-fork-merge.md b/design/pdd/19-phase13-cleanup-and-fork-merge.md
similarity index 100%
rename from docs/19-phase13-cleanup-and-fork-merge.md
rename to design/pdd/19-phase13-cleanup-and-fork-merge.md
diff --git a/docs/2-llm-call-lifecycle.md b/design/pdd/2-llm-call-lifecycle.md
similarity index 100%
rename from docs/2-llm-call-lifecycle.md
rename to design/pdd/2-llm-call-lifecycle.md
diff --git a/docs/20-phase14-document-and-embedding.md b/design/pdd/20-phase14-document-and-embedding.md
similarity index 100%
rename from docs/20-phase14-document-and-embedding.md
rename to design/pdd/20-phase14-document-and-embedding.md
diff --git a/docs/21-phase15-vector-store-persistence.md b/design/pdd/21-phase15-vector-store-persistence.md
similarity index 100%
rename from docs/21-phase15-vector-store-persistence.md
rename to design/pdd/21-phase15-vector-store-persistence.md
diff --git a/docs/22-phase16-summary-auto-generation.md b/design/pdd/22-phase16-summary-auto-generation.md
similarity index 100%
rename from docs/22-phase16-summary-auto-generation.md
rename to design/pdd/22-phase16-summary-auto-generation.md
diff --git a/docs/23-phase17-agent-execution-engine.md b/design/pdd/23-phase17-agent-execution-engine.md
similarity index 100%
rename from docs/23-phase17-agent-execution-engine.md
rename to design/pdd/23-phase17-agent-execution-engine.md
diff --git a/docs/24-phase18-agent-switch-and-dispatch.md b/design/pdd/24-phase18-agent-switch-and-dispatch.md
similarity index 100%
rename from docs/24-phase18-agent-switch-and-dispatch.md
rename to design/pdd/24-phase18-agent-switch-and-dispatch.md
diff --git a/docs/25-phase19-knowledge-graph-and-retrieval.md b/design/pdd/25-phase19-knowledge-graph-and-retrieval.md
similarity index 100%
rename from docs/25-phase19-knowledge-graph-and-retrieval.md
rename to design/pdd/25-phase19-knowledge-graph-and-retrieval.md
diff --git a/docs/26-step1-phase20-cargo-features-implementation.md b/design/pdd/26-step1-phase20-cargo-features-implementation.md
similarity index 100%
rename from docs/26-step1-phase20-cargo-features-implementation.md
rename to design/pdd/26-step1-phase20-cargo-features-implementation.md
diff --git a/docs/27-step3-phase26-ci-verification.md b/design/pdd/27-step3-phase26-ci-verification.md
similarity index 100%
rename from docs/27-step3-phase26-ci-verification.md
rename to design/pdd/27-step3-phase26-ci-verification.md
diff --git a/docs/28-phase28-openai-response-api-provider.md b/design/pdd/28-phase28-openai-response-api-provider.md
similarity index 100%
rename from docs/28-phase28-openai-response-api-provider.md
rename to design/pdd/28-phase28-openai-response-api-provider.md
diff --git a/docs/29-openai-response-provider-custom-headers.md b/design/pdd/29-openai-response-provider-custom-headers.md
similarity index 100%
rename from docs/29-openai-response-provider-custom-headers.md
rename to design/pdd/29-openai-response-provider-custom-headers.md
diff --git a/docs/3-phase0-remaining.md b/design/pdd/3-phase0-remaining.md
similarity index 100%
rename from docs/3-phase0-remaining.md
rename to design/pdd/3-phase0-remaining.md
diff --git a/docs/30-builtin-tools-injection-fix.md b/design/pdd/30-builtin-tools-injection-fix.md
similarity index 100%
rename from docs/30-builtin-tools-injection-fix.md
rename to design/pdd/30-builtin-tools-injection-fix.md
diff --git a/docs/4-prompt-engineering.md b/design/pdd/4-prompt-engineering.md
similarity index 100%
rename from docs/4-prompt-engineering.md
rename to design/pdd/4-prompt-engineering.md
diff --git a/docs/5-tool-system.md b/design/pdd/5-tool-system.md
similarity index 100%
rename from docs/5-tool-system.md
rename to design/pdd/5-tool-system.md
diff --git a/docs/6-memory-system.md b/design/pdd/6-memory-system.md
similarity index 100%
rename from docs/6-memory-system.md
rename to design/pdd/6-memory-system.md
diff --git a/docs/7-agent-runtime.md b/design/pdd/7-agent-runtime.md
similarity index 100%
rename from docs/7-agent-runtime.md
rename to design/pdd/7-agent-runtime.md
diff --git a/docs/8-examples-plan.md b/design/pdd/8-examples-plan.md
similarity index 100%
rename from docs/8-examples-plan.md
rename to design/pdd/8-examples-plan.md
diff --git a/docs/9-llm-provider-unified-interface.md b/design/pdd/9-llm-provider-unified-interface.md
similarity index 100%
rename from docs/9-llm-provider-unified-interface.md
rename to design/pdd/9-llm-provider-unified-interface.md
diff --git a/docs/9a-background-and-architecture.md b/design/pdd/9a-background-and-architecture.md
similarity index 100%
rename from docs/9a-background-and-architecture.md
rename to design/pdd/9a-background-and-architecture.md
diff --git a/docs/9b-ir-type-system.md b/design/pdd/9b-ir-type-system.md
similarity index 100%
rename from docs/9b-ir-type-system.md
rename to design/pdd/9b-ir-type-system.md
diff --git a/docs/9c-llm-provider-trait.md b/design/pdd/9c-llm-provider-trait.md
similarity index 100%
rename from docs/9c-llm-provider-trait.md
rename to design/pdd/9c-llm-provider-trait.md
diff --git a/docs/9d-provider-implementations.md b/design/pdd/9d-provider-implementations.md
similarity index 100%
rename from docs/9d-provider-implementations.md
rename to design/pdd/9d-provider-implementations.md
diff --git a/docs/9e-llm-cycle-and-upstream.md b/design/pdd/9e-llm-cycle-and-upstream.md
similarity index 100%
rename from docs/9e-llm-cycle-and-upstream.md
rename to design/pdd/9e-llm-cycle-and-upstream.md
diff --git a/docs/9f-edge-cases.md b/design/pdd/9f-edge-cases.md
similarity index 100%
rename from docs/9f-edge-cases.md
rename to design/pdd/9f-edge-cases.md
diff --git a/docs/9g-risk-and-migration.md b/design/pdd/9g-risk-and-migration.md
similarity index 100%
rename from docs/9g-risk-and-migration.md
rename to design/pdd/9g-risk-and-migration.md
diff --git a/design/prd/.gitkeep b/design/prd/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/design/roadmap/.gitkeep b/design/roadmap/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/roadmap-unsorted.md b/design/roadmap/roadmap-unsorted.md
similarity index 100%
rename from docs/roadmap-unsorted.md
rename to design/roadmap/roadmap-unsorted.md
diff --git a/docs/roadmap-v0.1.0.md b/design/roadmap/roadmap-v0.1.0.md
similarity index 100%
rename from docs/roadmap-v0.1.0.md
rename to design/roadmap/roadmap-v0.1.0.md
diff --git a/docs/roadmap-v0.2.0.md b/design/roadmap/roadmap-v0.2.0.md
similarity index 100%
rename from docs/roadmap-v0.2.0.md
rename to design/roadmap/roadmap-v0.2.0.md
diff --git a/docs/roadmap-v0.3.0.md b/design/roadmap/roadmap-v0.3.0.md
similarity index 100%
rename from docs/roadmap-v0.3.0.md
rename to design/roadmap/roadmap-v0.3.0.md
diff --git a/docs/roadmap-v0.3.2.md b/design/roadmap/roadmap-v0.3.2.md
similarity index 100%
rename from docs/roadmap-v0.3.2.md
rename to design/roadmap/roadmap-v0.3.2.md
diff --git a/docs/roadmap-v0.4.0.md b/design/roadmap/roadmap-v0.4.0.md
similarity index 100%
rename from docs/roadmap-v0.4.0.md
rename to design/roadmap/roadmap-v0.4.0.md
diff --git a/docs/roadmap.md b/design/roadmap/roadmap.md
similarity index 100%
rename from docs/roadmap.md
rename to design/roadmap/roadmap.md