@kaddo/cli 2.7.0 → 3.0.0

package/dist/index.js

@@ -79,7 +79,7 @@ async function multiselect2(opts) {
 
 // src/commands/init.ts
 var KADDO_DIR = ".kaddo";
-var ARCH_DIR = "architecture";
+var ARCH_DIR = "knowledge";
 function inferProjectName(dir) {
   const pkgPath = join(dir, "package.json");
   if (exists(pkgPath)) {
@@ -217,13 +217,13 @@ async function runInit() {
   };
   const kaddoConfigPath = join(dir, KADDO_DIR, "config.yml");
   writeFile(kaddoConfigPath, buildConfig(meta));
-  ensureDir(join(dir, ARCH_DIR, "work-items"));
+  ensureDir(join(dir, ARCH_DIR, "delivery", "work-items"));
   writeFile(join(dir, ARCH_DIR, "knowledge.md"), buildKnowledge(projectName.trim()));
-  writeFile(join(dir, ARCH_DIR, "roadmap.md"), buildRoadmap(projectName.trim()));
+  writeFile(join(dir, ARCH_DIR, "delivery", "roadmap.md"), buildRoadmap(projectName.trim()));
   log2.success("Created .kaddo/config.yml");
-  log2.success("Created architecture/knowledge.md");
-  log2.success("Created architecture/roadmap.md");
-  log2.success("Created architecture/work-items/");
+  log2.success("Created knowledge/knowledge.md");
+  log2.success("Created knowledge/delivery/roadmap.md");
+  log2.success("Created knowledge/delivery/work-items/");
   log2.info("Next: run `kaddo scan` to detect your stack.");
   outro2("Kaddo initialized.");
 }
@@ -669,20 +669,20 @@ async function writeBaselineArtifacts(dir, result) {
   const scanJsonPath = join(dir, ".kaddo", "scan.json");
   writeFile(scanJsonPath, serializeBaseline(baseline));
   log2.success("Wrote .kaddo/scan.json");
-  const inventoryPath = join(dir, "architecture", "inventory.md");
+  const inventoryPath = join(dir, "knowledge", "inventory.md");
   const inventoryExists = exists(inventoryPath);
   let writeInventory = true;
   if (inventoryExists) {
     writeInventory = await confirm2({
-      message: "architecture/inventory.md already exists. Overwrite it?",
+      message: "knowledge/inventory.md already exists. Overwrite it?",
       initialValue: true
     });
   }
   if (writeInventory) {
     writeFile(inventoryPath, renderInventory(baseline));
-    log2.success(`${inventoryExists ? "Updated" : "Wrote"} architecture/inventory.md`);
+    log2.success(`${inventoryExists ? "Updated" : "Wrote"} knowledge/inventory.md`);
   } else {
-    log2.info("Kept existing architecture/inventory.md.");
+    log2.info("Kept existing knowledge/inventory.md.");
   }
 }
 function printStateAwareNextStep(dir) {
@@ -895,10 +895,10 @@ var adrModule = {
   name: "adr",
   description: "Architectural Decision Records \u2014 document decisions when risk justifies it",
   configKey: "module_adr",
-  dirs: ["architecture/decisions"],
+  dirs: ["knowledge/tech/decisions"],
   files: [
     {
-      path: "architecture/decisions/.gitkeep",
+      path: "knowledge/tech/decisions/.gitkeep",
       content: ""
     }
   ],
@@ -956,10 +956,10 @@ var incidentModule = {
   name: "incident",
   description: "Incident records \u2014 document incidents, learnings, and preventive actions",
   configKey: "module_incident",
-  dirs: ["architecture/incidents"],
+  dirs: ["knowledge/incidents"],
   files: [
     {
-      path: "architecture/incidents/.gitkeep",
+      path: "knowledge/incidents/.gitkeep",
       content: ""
     }
   ],
@@ -1018,10 +1018,10 @@ var rfcModule = {
   name: "rfc",
   description: "Request for Comments \u2014 explore relevant changes before building them",
   configKey: "module_rfc",
-  dirs: ["architecture/rfcs"],
+  dirs: ["knowledge/rfcs"],
   files: [
     {
-      path: "architecture/rfcs/.gitkeep",
+      path: "knowledge/rfcs/.gitkeep",
       content: ""
     }
   ],
@@ -1071,10 +1071,10 @@ var migrationModule = {
   name: "migration",
   description: "Migration records \u2014 data, infra, or technology changes with more rigor",
   configKey: "module_migration",
-  dirs: ["architecture/migrations"],
+  dirs: ["knowledge/migrations"],
   files: [
     {
-      path: "architecture/migrations/.gitkeep",
+      path: "knowledge/migrations/.gitkeep",
       content: ""
     }
   ],
@@ -1132,10 +1132,10 @@ var legacyModule = {
   name: "legacy",
   description: "Legacy records \u2014 document systems with technical debt before modifying them",
   configKey: "module_legacy",
-  dirs: ["architecture/legacy"],
+  dirs: ["knowledge/legacy"],
   files: [
     {
-      path: "architecture/legacy/.gitkeep",
+      path: "knowledge/legacy/.gitkeep",
       content: ""
     }
   ],
@@ -1185,10 +1185,10 @@ var contractsModule = {
   name: "contracts",
   description: "API, event, and integration contracts \u2014 document shared interfaces before changing them",
   configKey: "module_contracts",
-  dirs: ["architecture/contracts"],
+  dirs: ["knowledge/contracts"],
   files: [
     {
-      path: "architecture/contracts/.gitkeep",
+      path: "knowledge/contracts/.gitkeep",
       content: ""
     }
   ],
@@ -1247,10 +1247,10 @@ var capabilitiesModule = {
   name: "capabilities",
   description: "Product capabilities \u2014 map what the product can do and link it to domains and decisions",
   configKey: "module_capabilities",
-  dirs: ["architecture/capabilities"],
+  dirs: ["knowledge/product/capabilities"],
   files: [
     {
-      path: "architecture/capabilities/.gitkeep",
+      path: "knowledge/product/capabilities/.gitkeep",
       content: ""
     }
   ],
@@ -1301,10 +1301,10 @@ var guardAdvancedModule = {
   name: "guard-advanced",
   description: "Advanced guard rules \u2014 CI blocking, critical artifact protection, domain-level thresholds",
   configKey: "module_guard_advanced",
-  dirs: ["architecture/guard-rules"],
+  dirs: ["knowledge/guard-rules"],
   files: [
     {
-      path: "architecture/guard-rules/rules.yml",
+      path: "knowledge/guard-rules/rules.yml",
       content: [
         "# Kaddo Guard Advanced \u2014 rules configuration",
         "# Uncomment and configure the rules you want to enforce.",
@@ -1405,7 +1405,7 @@ Optionally provide: README, existing docs, product notes, screenshots, API docum
 
 ## Expected Output
 
-A Markdown artifact intended to be saved as \`architecture/capabilities.md\`.
+A Markdown artifact intended to be saved as \`knowledge/product/capabilities.md\`.
 
 ## Instructions
 
@@ -1472,7 +1472,7 @@ Generated from Kaddo Context Pack.
 
 ## Where to Save the Result
 
-Save the output as \`architecture/capabilities.md\`.
+Save the output as \`knowledge/product/capabilities.md\`.
 
 ## Quality Checklist
 
@@ -1507,9 +1507,9 @@ Optionally provide: existing diagrams, infra config, README, dependency manifest
 
 Markdown artifacts intended to be saved as:
 
-- \`architecture/current-state.md\`
-- \`architecture/architecture-notes.md\`
-- \`architecture/decision-candidates.md\`
+- \`knowledge/tech/current-state.md\`
+- \`knowledge/tech/architecture-notes.md\`
+- \`knowledge/tech/decision-candidates.md\`
 
 ## Instructions
 
@@ -1555,9 +1555,9 @@ Generated from Kaddo Context Pack.
 
 ## Where to Save the Result
 
-Save the architecture overview as \`architecture/current-state.md\`, supporting notes as
-\`architecture/architecture-notes.md\`, and decision candidates as
-\`architecture/decision-candidates.md\`.
+Save the architecture overview as \`knowledge/tech/current-state.md\`, supporting notes as
+\`knowledge/tech/architecture-notes.md\`, and decision candidates as
+\`knowledge/tech/decision-candidates.md\`.
 
 ## Quality Checklist
 
@@ -1589,17 +1589,17 @@ Provide \`.kaddo/context-pack.md\` as the primary input.
 Optionally provide (use whatever is available; mark anything missing as an assumption or
 open question):
 
-- \`architecture/capabilities.md\`
-- \`architecture/current-state.md\`
-- \`architecture/legacy/risks.md\`
-- \`architecture/legacy/unknowns.md\`
-- \`architecture/decision-candidates.md\`
-- \`architecture/knowledge.md\`
+- \`knowledge/product/capabilities.md\`
+- \`knowledge/tech/current-state.md\`
+- \`knowledge/legacy/risks.md\`
+- \`knowledge/legacy/unknowns.md\`
+- \`knowledge/tech/decision-candidates.md\`
+- \`knowledge/knowledge.md\`
 - business priorities
 
 ## Expected Output
 
-A single Markdown artifact intended to be saved as \`architecture/roadmap.md\`.
+A single Markdown artifact intended to be saved as \`knowledge/delivery/roadmap.md\`.
 
 This roadmap is the bridge between understanding and execution. It must be structured enough
 that a future \`kaddo create --from roadmap\` command can read its candidate work items.
@@ -1706,7 +1706,7 @@ human review \u2014 not final commitments.
 
 ## Where to Save the Result
 
-Save the output as \`architecture/roadmap.md\`.
+Save the output as \`knowledge/delivery/roadmap.md\`.
 
 ## Quality Checklist
 
@@ -1744,9 +1744,9 @@ Optionally provide: incident history, known pain points, dependency manifests.
 
 Markdown artifacts intended to be saved as:
 
-- \`architecture/legacy/risks.md\`
-- \`architecture/legacy/unknowns.md\`
-- \`architecture/legacy/modernization-candidates.md\`
+- \`knowledge/legacy/risks.md\`
+- \`knowledge/legacy/unknowns.md\`
+- \`knowledge/legacy/modernization-candidates.md\`
 
 ## Instructions
 
@@ -1796,9 +1796,9 @@ Generated from Kaddo Context Pack.
 
 ## Where to Save the Result
 
-Save risks as \`architecture/legacy/risks.md\`, unknowns as
-\`architecture/legacy/unknowns.md\`, and modernization candidates as
-\`architecture/legacy/modernization-candidates.md\`.
+Save risks as \`knowledge/legacy/risks.md\`, unknowns as
+\`knowledge/legacy/unknowns.md\`, and modernization candidates as
+\`knowledge/legacy/modernization-candidates.md\`.
 
 ## Quality Checklist
 
@@ -1826,11 +1826,11 @@ to capture decisions that are implicit in the system.
 
 Provide \`.kaddo/context-pack.md\` as the primary input.
 
-Optionally provide: \`architecture/current-state.md\`, \`architecture/architecture-notes.md\`.
+Optionally provide: \`knowledge/tech/current-state.md\`, \`knowledge/tech/architecture-notes.md\`.
 
 ## Expected Output
 
-A Markdown artifact intended to be saved as \`architecture/decision-candidates.md\`.
+A Markdown artifact intended to be saved as \`knowledge/tech/decision-candidates.md\`.
 
 ## Instructions
 
@@ -1876,7 +1876,7 @@ Generated from Kaddo Context Pack.
 
 ## Where to Save the Result
 
-Save the output as \`architecture/decision-candidates.md\`.
+Save the output as \`knowledge/tech/decision-candidates.md\`.
 
 ## Quality Checklist
 
@@ -1897,7 +1897,7 @@ Work Item actionable for a human.
 
 ## When to Use
 
-Use this agent after a roadmap exists (\`architecture/roadmap.md\`) or when an existing Work
+Use this agent after a roadmap exists (\`knowledge/delivery/roadmap.md\`) or when an existing Work
 Item is vague, too large, or missing acceptance criteria.
 
 ## Input Required
@@ -1907,7 +1907,7 @@ existing Work Item file to refine.
 
 ## Expected Output
 
-A refined Work Item intended to be saved as \`architecture/work-items/*.md\`.
+A refined Work Item intended to be saved as \`knowledge/delivery/work-items/*.md\`.
 
 ## Instructions
 
@@ -1948,7 +1948,7 @@ A refined Work Item intended to be saved as \`architecture/work-items/*.md\`.
 
 ## Where to Save the Result
 
-Save the output as a file under \`architecture/work-items/\`.
+Save the output as a file under \`knowledge/delivery/work-items/\`.
 
 ## Quality Checklist
 
@@ -1979,7 +1979,7 @@ structure (from \`.kaddo/config.yml\`) are especially relevant.
 
 ## Expected Output
 
-A Markdown artifact intended to be saved as \`architecture/git-strategy.md\`.
+A Markdown artifact intended to be saved as \`knowledge/tech/git-strategy.md\`.
 
 ## Instructions
 
@@ -2019,7 +2019,7 @@ GitHub Flow + Conventional Commits + SemVer
 
 ## Where to Save the Result
 
-Save the output as \`architecture/git-strategy.md\`. Optionally record machine config in
+Save the output as \`knowledge/tech/git-strategy.md\`. Optionally record machine config in
 \`.kaddo/git.yml\`.
 
 ## Quality Checklist
@@ -2051,8 +2051,8 @@ module's \`module-design.md\` if it exists.
 
 ## Expected Output
 
-A Markdown artifact intended to be saved as \`architecture/security.md\` or
-\`architecture/modules/<module-name>/security.md\`.
+A Markdown artifact intended to be saved as \`knowledge/tech/security.md\` or
+\`knowledge/tech/modules/<module-name>/security.md\`.
 
 ## Instructions
 
@@ -2090,8 +2090,8 @@ A Markdown artifact intended to be saved as \`architecture/security.md\` or
 
 ## Where to Save the Result
 
-Save as \`architecture/security.md\` (global) or
-\`architecture/modules/<module-name>/security.md\` (per module).
+Save as \`knowledge/tech/security.md\` (global) or
+\`knowledge/tech/modules/<module-name>/security.md\` (per module).
 
 ## Quality Checklist
 
@@ -2119,8 +2119,8 @@ Provide \`.kaddo/context-pack.md\` as the primary input.
 
 ## Expected Output
 
-A Markdown artifact intended to be saved as \`architecture/standards.md\` or
-\`architecture/modules/<module-name>/standards.md\`.
+A Markdown artifact intended to be saved as \`knowledge/tech/standards.md\` or
+\`knowledge/tech/modules/<module-name>/standards.md\`.
 
 ## Instructions
 
@@ -2152,8 +2152,8 @@ A Markdown artifact intended to be saved as \`architecture/standards.md\` or
 
 ## Where to Save the Result
 
-Save as \`architecture/standards.md\` (global) or
-\`architecture/modules/<module-name>/standards.md\` (per module).
+Save as \`knowledge/tech/standards.md\` (global) or
+\`knowledge/tech/modules/<module-name>/standards.md\` (per module).
 
 ## Quality Checklist
 
@@ -2183,8 +2183,8 @@ especially relevant.
 
 ## Expected Output
 
-A Markdown artifact intended to be saved as \`architecture/stack.md\` or
-\`architecture/modules/<module-name>/stack.md\`.
+A Markdown artifact intended to be saved as \`knowledge/tech/stack.md\` or
+\`knowledge/tech/modules/<module-name>/stack.md\`.
 
 ## Instructions
 
@@ -2220,8 +2220,8 @@ A Markdown artifact intended to be saved as \`architecture/stack.md\` or
 
 ## Where to Save the Result
 
-Save as \`architecture/stack.md\` (global) or
-\`architecture/modules/<module-name>/stack.md\` (per module).
+Save as \`knowledge/tech/stack.md\` (global) or
+\`knowledge/tech/modules/<module-name>/stack.md\` (per module).
 
 ## Quality Checklist
 
@@ -2242,7 +2242,7 @@ mark assumptions.
 ## When to Use
 
 Use this agent after \`kaddo modules map\`, to fill in the generated
-\`architecture/modules/<module-name>/module-design.md\`.
+\`knowledge/tech/modules/<module-name>/module-design.md\`.
 
 ## Input Required
 
@@ -2252,7 +2252,7 @@ Provide \`.kaddo/context-pack.md\` as the primary input, plus the module entry i
 ## Expected Output
 
 A Markdown artifact intended to be saved as
-\`architecture/modules/<module-name>/module-design.md\`.
+\`knowledge/tech/modules/<module-name>/module-design.md\`.
 
 ## Instructions
 
@@ -2295,7 +2295,7 @@ A Markdown artifact intended to be saved as
 
 ## Where to Save the Result
 
-Save as \`architecture/modules/<module-name>/module-design.md\`.
+Save as \`knowledge/tech/modules/<module-name>/module-design.md\`.
 
 ## Quality Checklist
 
@@ -2304,6 +2304,171 @@ Save as \`architecture/modules/<module-name>/module-design.md\`.
 - Diagrams are suggested, not generated.
 - Assumptions and risks are explicit.
 `;
+var BUSINESS_AGENT = `# Business Agent
+
+## Role
+
+You are the Kaddo Business Agent. You help turn an initial idea into a clear business
+definition for a new project. You do not write code and you do not invent facts \u2014 you ask
+for missing information and mark unknowns.
+
+## When to Use
+
+Use this agent after \`kaddo bootstrap\`, when refining the artifacts under
+\`knowledge/business/\`.
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\` (if available) and the founder/team's notes about the
+idea: problem, intended users, value, constraints.
+
+## Expected Output
+
+Refined Markdown for \`knowledge/business/*.md\`: product brief, problem statement,
+users/personas, value proposition, business rules, constraints and glossary.
+
+## Instructions
+
+1. Clarify the problem without assuming the solution.
+2. Identify primary and secondary users with goals.
+3. State the value proposition specifically.
+4. Capture business rules as testable statements.
+5. List real constraints (business, regulatory, resources).
+6. Build a shared glossary.
+7. Mark every uncertainty as an assumption or open question.
+
+## Constraints
+
+- Do not invent business facts; ask instead.
+- Do not write code or choose a stack.
+- Keep each artifact lightweight and high-value.
+- Mark assumptions and open questions explicitly.
+
+## Output Format
+
+One Markdown section per \`knowledge/business/*.md\` artifact, keeping the template
+headings.
+
+## Where to Save the Result
+
+Save into \`knowledge/business/\` (product-brief.md, problem.md, users.md,
+value-proposition.md, business-rules.md, constraints.md, glossary.md).
+
+## Quality Checklist
+
+- The problem is stated without assuming the solution.
+- Users have goals, not just labels.
+- Rules are testable and free of implementation detail.
+- Assumptions and open questions are explicit.
+`;
+var BOOTSTRAP_AGENT = `# Bootstrap Agent
+
+## Role
+
+You are the Kaddo Bootstrap Agent. You guide the transition from business definition to an
+initial architecture direction, quality attributes, a roadmap and first Work Items for a
+new project. You propose; the human decides.
+
+## When to Use
+
+Use this agent after \`kaddo bootstrap\` and after the business artifacts are drafted.
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\` and the \`knowledge/business/*.md\` artifacts.
+
+## Expected Output
+
+Refined Markdown for \`knowledge/bootstrap-summary.md\`, \`knowledge/product/capabilities.md\`,
+\`knowledge/tech/quality-attributes.md\` and \`knowledge/delivery/roadmap.md\`, plus candidate Work
+Items.
+
+## Instructions
+
+1. Derive candidate capabilities from the business definition.
+2. Propose prioritized quality attributes and accepted trade-offs.
+3. Outline an initial architecture direction (no final decisions \u2014 list candidates).
+4. Propose a prioritized roadmap of candidate Work Items with suggested Knowledge Levels.
+5. Keep a clear next step and open questions.
+
+## Constraints
+
+- Do not call any external service; you run in the human's chat.
+- Do not decide architecture unilaterally \u2014 mark decisions as candidates (ADR later).
+- Do not write production code.
+- Do not invent business facts.
+
+## Output Format
+
+Markdown matching the bootstrap-summary, capabilities, quality-attributes and roadmap
+templates.
+
+## Where to Save the Result
+
+Save to \`knowledge/bootstrap-summary.md\`, \`knowledge/product/capabilities.md\`,
+\`knowledge/tech/quality-attributes.md\` and \`knowledge/delivery/roadmap.md\`.
+
+## Quality Checklist
+
+- Capabilities trace back to the business definition.
+- Quality attributes are prioritized, not all "high".
+- Roadmap candidates are compatible with \`kaddo create --from roadmap\`.
+- Open questions and assumptions are explicit.
+`;
+var CODEBASE_FOUNDATION_AGENT = `# Codebase Foundation Agent
+
+## Role
+
+You are the Kaddo Codebase Foundation Agent. You propose a coherent codebase foundation \u2014
+structure, modules, boundaries and conventions \u2014 aligned with the business, the initial
+architecture and the candidate stack. You do **not** write production code.
+
+## When to Use
+
+Use this agent after the business and initial architecture artifacts exist, when refining
+\`knowledge/tech/codebase.md\`.
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\`, \`knowledge/business/*.md\`,
+\`knowledge/product/capabilities.md\`, \`knowledge/tech/quality-attributes.md\` and
+\`knowledge/tech/stack.md\`.
+
+## Expected Output
+
+Refined Markdown for \`knowledge/tech/codebase.md\`.
+
+## Instructions
+
+1. Propose a suggested folder/module structure that follows the domain, not a framework
+   default.
+2. Define initial boundaries between modules.
+3. Recommend conventions (naming, layering, testing expectations).
+4. State minimum criteria to start development.
+5. Reference the Git strategy rather than restating it.
+
+## Constraints
+
+- Do not write production code or create implementation files.
+- Do not install or assume a specific framework's scaffolding.
+- Keep it a foundation, not a full design.
+- Mark assumptions and open questions explicitly.
+
+## Output Format
+
+Markdown matching the codebase-foundation template headings.
+
+## Where to Save the Result
+
+Save as \`knowledge/tech/codebase.md\`.
+
+## Quality Checklist
+
+- Structure follows business and architecture, not a framework default.
+- No production code is described.
+- Minimum criteria to start development are explicit.
+- Assumptions and open questions are listed.
+`;
 var AGENT_PROMPTS = [
   { fileName: "capability-agent.md", content: CAPABILITY_AGENT },
   { fileName: "architecture-agent.md", content: ARCHITECTURE_AGENT },
@@ -2315,12 +2480,16 @@ var AGENT_PROMPTS = [
   { fileName: "security-agent.md", content: SECURITY_AGENT },
   { fileName: "standards-agent.md", content: STANDARDS_AGENT },
   { fileName: "stack-agent.md", content: STACK_AGENT },
-  { fileName: "module-design-agent.md", content: MODULE_DESIGN_AGENT }
+  { fileName: "module-design-agent.md", content: MODULE_DESIGN_AGENT },
+  // Bootstrap agents (new projects)
+  { fileName: "business-agent.md", content: BUSINESS_AGENT },
+  { fileName: "bootstrap-agent.md", content: BOOTSTRAP_AGENT },
+  { fileName: "codebase-agent.md", content: CODEBASE_FOUNDATION_AGENT }
 ];
 
 // src/modules/agents.ts
 var agentReadme = {
-  path: "architecture/agents/README.md",
+  path: "knowledge/agents/README.md",
   content: [
     "# Agents",
     "",
@@ -2338,12 +2507,18 @@ var agentReadme = {
     "",
     "## Recommended order by project state",
     "",
-    "- **new** \u2192 roadmap-agent \u2192 architecture-agent",
+    "- **new** \u2192 business-agent \u2192 bootstrap-agent \u2192 codebase-agent \u2192 roadmap-agent",
     "- **pre-ai** \u2192 capability-agent \u2192 architecture-agent \u2192 roadmap-agent",
     "- **legacy** \u2192 legacy-agent \u2192 architecture-agent \u2192 capability-agent \u2192 roadmap-agent",
     "",
     "## Installed agents",
     "",
+    "### Bootstrap agents (new projects)",
+    "",
+    "- `business-agent.md` \u2014 turn an idea into a business definition.",
+    "- `bootstrap-agent.md` \u2014 go from business to capabilities, quality attributes and roadmap.",
+    "- `codebase-agent.md` \u2014 propose a codebase foundation (no code).",
+    "",
     "### Understanding agents",
     "",
     "- `capability-agent.md` \u2014 extract/propose system capabilities.",
@@ -2363,14 +2538,14 @@ var agentReadme = {
   ].join("\n")
 };
 var agentFiles = AGENT_PROMPTS.map((a) => ({
-  path: `architecture/agents/${a.fileName}`,
+  path: `knowledge/agents/${a.fileName}`,
   content: a.content
 }));
 var agentsModule = {
   name: "agents",
   description: "Agent prompt packs \u2014 Markdown prompts to turn context packs into knowledge in your LLM",
   configKey: "module_agents",
-  dirs: ["architecture/agents"],
+  dirs: ["knowledge/agents"],
   files: [agentReadme, ...agentFiles],
   workItemTypes: [
     {
@@ -2419,14 +2594,14 @@ var skillsModule = {
   name: "skills",
   description: "Reusable skills \u2014 capabilities shared across agents, teams, or projects",
   configKey: "module_skills",
-  dirs: ["architecture/skills"],
+  dirs: ["knowledge/skills"],
   files: [
     {
-      path: "architecture/skills/.gitkeep",
+      path: "knowledge/skills/.gitkeep",
       content: ""
     },
     {
-      path: "architecture/skills/README.md",
+      path: "knowledge/skills/README.md",
       content: [
         "# Skills",
         "",
@@ -2639,33 +2814,33 @@ var standardsModule = {
   name: "standards",
   description: "Global standards starter \u2014 lightweight coding, docs and testing conventions",
   configKey: "module_standards",
-  dirs: ["architecture"],
-  files: [{ path: "architecture/standards.md", content: standardsTemplate }],
+  dirs: ["knowledge"],
+  files: [{ path: "knowledge/tech/standards.md", content: standardsTemplate }],
   workItemTypes: []
 };
 var securityModule = {
   name: "security",
   description: "Global security starter \u2014 document security considerations (no scanning)",
   configKey: "module_security",
-  dirs: ["architecture"],
-  files: [{ path: "architecture/security.md", content: securityTemplate }],
+  dirs: ["knowledge"],
+  files: [{ path: "knowledge/tech/security.md", content: securityTemplate }],
   workItemTypes: []
 };
 var stackModule = {
   name: "stack",
   description: "Global stack starter \u2014 document technologies and stack decisions",
   configKey: "module_stack",
-  dirs: ["architecture"],
-  files: [{ path: "architecture/stack.md", content: stackTemplate }],
+  dirs: ["knowledge"],
+  files: [{ path: "knowledge/tech/stack.md", content: stackTemplate }],
   workItemTypes: []
 };
 var gitStrategyModule = {
   name: "git-strategy",
   description: "Git strategy starter \u2014 default GitHub Flow + Conventional Commits + SemVer",
   configKey: "module_git_strategy",
-  dirs: ["architecture"],
+  dirs: ["knowledge"],
   files: [
-    { path: "architecture/git-strategy.md", content: gitStrategyTemplate },
+    { path: "knowledge/tech/git-strategy.md", content: gitStrategyTemplate },
     { path: ".kaddo/git.yml", content: gitYml }
   ],
   workItemTypes: []
@@ -2821,8 +2996,8 @@ function parseRoadmapCandidates(markdown) {
 }
 
 // src/commands/create.ts
-var WORK_ITEMS_DIR = "architecture/work-items";
-var ROADMAP_PATH = "architecture/roadmap.md";
+var WORK_ITEMS_DIR = "knowledge/delivery/work-items";
+var ROADMAP_PATH = "knowledge/delivery/roadmap.md";
 function printStateGuidance(dir) {
   let config;
   try {
@@ -3443,7 +3618,7 @@ function toStringArray(value) {
   return Array.isArray(value) ? value.map((v) => String(v)).filter(Boolean) : [];
 }
 function moduleArtifactCoverage(dir, id) {
-  const base = join(dir, "architecture", "modules", id);
+  const base = join(dir, "knowledge", "tech", "modules", id);
   return {
     moduleDesign: exists(join(base, "module-design.md")),
     stack: exists(join(base, "stack.md")),
@@ -3734,7 +3909,7 @@ function collectMatchedDomains(matchedArtifactDomains) {
 }
 
 // src/commands/guard.ts
-var ARCH_DIR2 = "architecture";
+var ARCH_DIR2 = "knowledge";
 var CONFIG_PATH2 = ".kaddo/config.yml";
 function loadConfig2(dir) {
   const configPath = join(dir, CONFIG_PATH2);
@@ -3880,7 +4055,7 @@ async function runGuard(opts = {}) {
   }
   const archDir = join(dir, ARCH_DIR2);
   if (!exists(archDir)) {
-    console.log("kaddo guard: no architecture/ directory found. Run `kaddo init` first.");
+    console.log("kaddo guard: no knowledge/ directory found. Run `kaddo init` first.");
     return;
   }
   const artifacts = readArtifacts(archDir);
@@ -3995,8 +4170,60 @@ function runIgnoreRemove(artifactId) {
 import matter2 from "gray-matter";
 import { parse as parseYaml8 } from "yaml";
 
+// src/core/layers.ts
+var KNOWLEDGE = "knowledge";
+var LAYER_SPEC = [
+  {
+    layer: "Business",
+    items: [
+      { name: "problem", path: `${KNOWLEDGE}/business/problem.md` },
+      { name: "users", path: `${KNOWLEDGE}/business/users.md` },
+      { name: "value-proposition", path: `${KNOWLEDGE}/business/value-proposition.md` },
+      { name: "constraints", path: `${KNOWLEDGE}/business/constraints.md` },
+      { name: "business-rules", path: `${KNOWLEDGE}/business/business-rules.md` }
+    ]
+  },
+  {
+    layer: "Product",
+    items: [
+      { name: "product brief", path: `${KNOWLEDGE}/product/product-brief.md` },
+      { name: "capabilities", path: `${KNOWLEDGE}/product/capabilities.md` }
+    ]
+  },
+  {
+    layer: "Tech",
+    items: [
+      { name: "codebase", path: `${KNOWLEDGE}/tech/codebase.md` },
+      { name: "current-state", path: `${KNOWLEDGE}/tech/current-state.md` },
+      { name: "decisions", path: `${KNOWLEDGE}/tech/decisions` }
+    ]
+  },
+  {
+    layer: "Delivery",
+    items: [
+      { name: "roadmap", path: `${KNOWLEDGE}/delivery/roadmap.md` },
+      { name: "work items", path: `${KNOWLEDGE}/delivery/work-items` }
+    ]
+  }
+];
+function knowledgeLayers(dir) {
+  return LAYER_SPEC.map(({ layer, items }) => ({
+    layer,
+    items: items.map((it) => ({ name: it.name, present: exists(join(dir, it.path)) }))
+  }));
+}
+function renderLayersMarkdown(layers) {
+  const lines = [];
+  for (const { layer, items } of layers) {
+    lines.push(`### ${layer}`);
+    for (const it of items) lines.push(`- ${it.present ? "\u2713" : "\u2717"} ${it.name}`);
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+
 // src/core/project-explain.ts
-var ARCH_DIR3 = "architecture";
+var ARCH_DIR3 = "knowledge";
 function first(values) {
   if (Array.isArray(values)) {
     const v = values.find((x) => typeof x === "string" && x);
@@ -4054,9 +4281,9 @@ function buildProjectExplanation(dir) {
     hasInventory: exists(join(dir, ARCH_DIR3, "inventory.md")),
     hasContextPack: exists(join(dir, ".kaddo", "context-pack.md")),
     hasUnderstand: exists(join(dir, ".kaddo", "understand.md")),
-    hasCapabilities: exists(join(dir, ARCH_DIR3, "capabilities.md")),
-    hasArchitecture: exists(join(dir, ARCH_DIR3, "current-state.md")),
-    hasRoadmap: exists(join(dir, ARCH_DIR3, "roadmap.md")),
+    hasCapabilities: exists(join(dir, ARCH_DIR3, "product", "capabilities.md")),
+    hasArchitecture: exists(join(dir, ARCH_DIR3, "tech", "current-state.md")),
+    hasRoadmap: exists(join(dir, ARCH_DIR3, "delivery", "roadmap.md")),
     hasAgents: hasAgents(dir)
   };
   const archDir = join(dir, ARCH_DIR3);
@@ -4090,14 +4317,14 @@ function buildProjectExplanation(dir) {
   const missingKnowledge = [];
   if (!knowledge.hasScan) missingKnowledge.push("Scan baseline (.kaddo/scan.json)");
   if (!knowledge.hasContextPack) missingKnowledge.push("Context pack (.kaddo/context-pack.md)");
-  if (!knowledge.hasInventory) missingKnowledge.push("Inventory (architecture/inventory.md)");
+  if (!knowledge.hasInventory) missingKnowledge.push("Inventory (knowledge/inventory.md)");
   if (!knowledge.hasCapabilities)
-    missingKnowledge.push("Capabilities (architecture/capabilities.md)");
+    missingKnowledge.push("Capabilities (knowledge/product/capabilities.md)");
   if (!knowledge.hasArchitecture)
-    missingKnowledge.push("Architecture baseline (architecture/current-state.md)");
-  if (!knowledge.hasRoadmap) missingKnowledge.push("Roadmap (architecture/roadmap.md)");
-  if (!knowledge.hasAgents) missingKnowledge.push("Agents (architecture/agents/)");
-  if (items.length === 0) missingKnowledge.push("Work items (architecture/work-items/)");
+    missingKnowledge.push("Architecture baseline (knowledge/tech/current-state.md)");
+  if (!knowledge.hasRoadmap) missingKnowledge.push("Roadmap (knowledge/delivery/roadmap.md)");
+  if (!knowledge.hasAgents) missingKnowledge.push("Agents (knowledge/agents/)");
+  if (items.length === 0) missingKnowledge.push("Work items (knowledge/delivery/work-items/)");
   const suggestedNextSteps = [];
   if (!knowledge.hasScan) {
     suggestedNextSteps.push("Run `kaddo scan` to detect the technical stack.");
@@ -4108,13 +4335,13 @@ function buildProjectExplanation(dir) {
     suggestedNextSteps.push("Run `kaddo add agents` to install knowledge agents.");
   }
   if (!knowledge.hasCapabilities) {
-    suggestedNextSteps.push("Use capability-agent to generate architecture/capabilities.md.");
+    suggestedNextSteps.push("Use capability-agent to generate knowledge/product/capabilities.md.");
   }
   if (!knowledge.hasArchitecture) {
-    suggestedNextSteps.push("Use architecture-agent to generate architecture/current-state.md.");
+    suggestedNextSteps.push("Use architecture-agent to generate knowledge/tech/current-state.md.");
   }
   if (!knowledge.hasRoadmap) {
-    suggestedNextSteps.push("Use roadmap-agent to generate architecture/roadmap.md.");
+    suggestedNextSteps.push("Use roadmap-agent to generate knowledge/delivery/roadmap.md.");
   }
   if (items.length === 0) {
     suggestedNextSteps.push("Create your first Work Item with `kaddo create`.");
@@ -4130,6 +4357,7 @@ function buildProjectExplanation(dir) {
     workItems,
     ownership,
     domains,
+    layers: knowledgeLayers(dir),
     mappedModules,
     missingKnowledge,
     suggestedNextSteps
@@ -4148,6 +4376,9 @@ function renderExplanationHuman(exp) {
   lines.push(`- Team: ${exp.project.teamSize}`);
   lines.push(`- Structure: ${exp.project.structure}`);
   lines.push("");
+  lines.push("## Knowledge Layers");
+  lines.push(renderLayersMarkdown(exp.layers));
+  lines.push("");
   if (exp.stack) {
     lines.push("## Detected Stack");
     if (exp.stack.language) lines.push(`- Language: ${exp.stack.language}`);
@@ -4225,7 +4456,7 @@ function renderExplanationAgent(exp) {
 }
 
 // src/commands/explain.ts
-var ARCH_DIR4 = "architecture";
+var ARCH_DIR4 = "knowledge";
 var CONFIG_PATH3 = ".kaddo/config.yml";
 function readKnowledge(dir) {
   const knowledgePath = join(dir, ARCH_DIR4, "knowledge.md");
@@ -4390,7 +4621,7 @@ function runExplain(opts) {
   }
   const archDir = join(dir, ARCH_DIR4);
   if (!exists(archDir)) {
-    console.error("No architecture/ directory found. Run `kaddo init` first.");
+    console.error("No knowledge/ directory found. Run `kaddo init` first.");
     process.exit(1);
   }
   let artifacts = readArtifacts(archDir);
@@ -4413,7 +4644,7 @@ function runExplain(opts) {
 // src/core/context-pack.ts
 import matter3 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
-var ARCH_DIR5 = "architecture";
+var ARCH_DIR5 = "knowledge";
 function readScanJson(dir) {
   const scanPath = join(dir, ".kaddo", "scan.json");
   if (!exists(scanPath)) return null;
@@ -4504,7 +4735,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   if (!knowledgeSummary) {
     missing.push("No project knowledge summary found yet.");
   }
-  const roadmapSummary = readMarkdownSummary(dir, "roadmap.md") ?? "";
+  const roadmapSummary = readMarkdownSummary(dir, "delivery/roadmap.md") ?? "";
   if (!roadmapSummary) {
     missing.push("No roadmap baseline found.");
   }
@@ -4518,6 +4749,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   }
   const state = config.project.state;
   const mappedModules = loadMappedModules(dir);
+  const layers = knowledgeLayers(dir);
   return {
     version: CONTEXT_PACK_VERSION,
     generatedAt: now.toISOString(),
@@ -4544,6 +4776,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       workItems: workItems.map(toContextWorkItem),
       artifacts: workItems.filter((a) => a.codeGlobs.length > 0).map(toContextArtifact)
     },
+    layers,
     mappedModules,
     missing,
     handoff: {
@@ -4577,6 +4810,11 @@ function renderContextPack(pack) {
       `- Structure: ${project.structure}`
     ].join("\n") + "\n"
   );
+  parts.push("## Knowledge Layers\n");
+  parts.push(
+    "Project knowledge is organized in four layers: **Business \u2192 Product \u2192 Tech \u2192 Delivery**.\n"
+  );
+  parts.push(renderLayersMarkdown(pack.layers) + "\n");
   parts.push("## Technical Inventory\n");
   if (scan2.available) {
     const lines = [
@@ -4706,22 +4944,22 @@ function flowForState(state) {
   switch (state) {
     case "new":
       return [
-        { agent: "roadmap-agent.md", output: "architecture/roadmap.md" },
-        { agent: "architecture-agent.md", output: "architecture/current-state.md" }
+        { agent: "roadmap-agent.md", output: "knowledge/delivery/roadmap.md" },
+        { agent: "architecture-agent.md", output: "knowledge/tech/current-state.md" }
       ];
     case "legacy":
       return [
-        { agent: "legacy-agent.md", output: "architecture/legacy/risks.md" },
-        { agent: "architecture-agent.md", output: "architecture/current-state.md" },
-        { agent: "capability-agent.md", output: "architecture/capabilities.md" },
-        { agent: "roadmap-agent.md", output: "architecture/roadmap.md" }
+        { agent: "legacy-agent.md", output: "knowledge/legacy/risks.md" },
+        { agent: "architecture-agent.md", output: "knowledge/tech/current-state.md" },
+        { agent: "capability-agent.md", output: "knowledge/product/capabilities.md" },
+        { agent: "roadmap-agent.md", output: "knowledge/delivery/roadmap.md" }
       ];
     case "pre-ai":
     default:
       return [
-        { agent: "capability-agent.md", output: "architecture/capabilities.md" },
-        { agent: "architecture-agent.md", output: "architecture/current-state.md" },
-        { agent: "roadmap-agent.md", output: "architecture/roadmap.md" }
+        { agent: "capability-agent.md", output: "knowledge/product/capabilities.md" },
+        { agent: "architecture-agent.md", output: "knowledge/tech/current-state.md" },
+        { agent: "roadmap-agent.md", output: "knowledge/delivery/roadmap.md" }
       ];
   }
 }
@@ -4729,11 +4967,11 @@ function buildUnderstandPlan(dir, config) {
   const state = config.project.state;
   const flow = flowForState(state);
   const steps = flow.map((s) => {
-    const installed = exists(join(dir, "architecture", "agents", s.agent));
+    const installed = exists(join(dir, "knowledge", "agents", s.agent));
     return { agent: s.agent, output: s.output, installed };
   });
   const missingAgents = steps.filter((s) => !s.installed).map((s) => s.agent);
-  const agentsInstalled = exists(join(dir, "architecture", "agents")) && missingAgents.length === 0;
+  const agentsInstalled = exists(join(dir, "knowledge", "agents")) && missingAgents.length === 0;
   return {
     project: {
       name: config.project.name,
@@ -4787,7 +5025,7 @@ function renderUnderstand(plan) {
 `);
   parts.push("## Agent Prompts\n");
   parts.push(
-    steps.map((s) => `- \`architecture/agents/${s.agent}\``).join("\n") + "\n"
+    steps.map((s) => `- \`knowledge/agents/${s.agent}\``).join("\n") + "\n"
   );
   parts.push("## Expected Outputs\n");
   parts.push(steps.map((s) => `- \`${s.output}\``).join("\n") + "\n");
@@ -4800,7 +5038,7 @@ function renderUnderstand(plan) {
         "",
         "1. Open your preferred LLM chat (Claude, ChatGPT, Cursor, Copilot, Windsurf\u2026).",
         `2. Paste the context pack: \`${plan.contextPackPath}\``,
-        `3. Paste the agent prompt: \`architecture/agents/${first2.agent}\``,
+        `3. Paste the agent prompt: \`knowledge/agents/${first2.agent}\``,
         `4. Ask the LLM to produce: \`${first2.output}\``,
         `5. Save the result in: \`${first2.output}\``
       ].join("\n") + "\n"
@@ -4839,7 +5077,7 @@ function renderUnderstandTerminal(plan) {
     lines.push(`First step: use ${agentName(first2.agent)}.`);
     lines.push("");
     lines.push(`  Context:         ${plan.contextPackPath}`);
-    lines.push(`  Agent prompt:    architecture/agents/${first2.agent}`);
+    lines.push(`  Agent prompt:    knowledge/agents/${first2.agent}`);
     lines.push(`  Expected output: ${first2.output}`);
     lines.push("");
   }
@@ -5040,7 +5278,7 @@ function classify(declaredType, declaredLevel, touchedFiles) {
 }
 
 // src/commands/classify.ts
-var ARCH_DIR6 = "architecture";
+var ARCH_DIR6 = "knowledge";
 function findActiveWorkItem(dir) {
   const archDir = join(dir, ARCH_DIR6);
   if (!exists(archDir)) return null;
@@ -5108,7 +5346,7 @@ async function runClassify(opts = {}) {
 
 // src/commands/status.ts
 import { parse as parseYaml9 } from "yaml";
-var ARCH_DIR7 = "architecture";
+var ARCH_DIR7 = "knowledge";
 var CONFIG_PATH4 = ".kaddo/config.yml";
 function loadConfig3(dir) {
   const p2 = join(dir, CONFIG_PATH4);
@@ -5122,7 +5360,7 @@ function loadConfig3(dir) {
 function runStatus() {
   const dir = cwd();
   if (!exists(join(dir, ARCH_DIR7))) {
-    console.error("No architecture/ directory found. Run `kaddo init` first.");
+    console.error("No knowledge/ directory found. Run `kaddo init` first.");
     process.exit(1);
   }
   const config = loadConfig3(dir);
@@ -5172,8 +5410,8 @@ function runStatus() {
 
 // src/commands/learn.ts
 import matter4 from "gray-matter";
-var ARCH_DIR8 = "architecture";
-var WORK_ITEMS_DIR2 = "architecture/work-items";
+var ARCH_DIR8 = "knowledge";
+var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 function findWorkItemFile(dir, id) {
   const wiDir = join(dir, WORK_ITEMS_DIR2);
   if (!exists(wiDir)) return null;
@@ -5214,7 +5452,7 @@ ${learning.trim()}
 async function runLearn(artifactId) {
   const dir = cwd();
   if (!exists(join(dir, ARCH_DIR8))) {
-    console.error("No architecture/ directory found. Run `kaddo init` first.");
+    console.error("No knowledge/ directory found. Run `kaddo init` first.");
     process.exit(1);
   }
   intro2("kaddo learn");
@@ -5256,12 +5494,12 @@ async function runLearn(artifactId) {
   updateWorkItemFile(filePath, learning.trim());
   log2.success(`${targetId} marked as done`);
   log2.success(`Learning recorded in ${filePath.replace(dir + "/", "")}`);
-  log2.info("Consider updating architecture/knowledge.md if this changes the current state.");
+  log2.info("Consider updating knowledge/knowledge.md if this changes the current state.");
   outro2("Work item closed.");
 }
 
 // src/commands/history.ts
-var ARCH_DIR9 = "architecture";
+var ARCH_DIR9 = "knowledge";
 function formatRow(a) {
   const id = (a.id || "").padEnd(8);
   const type = a.type.padEnd(18);
@@ -5273,7 +5511,7 @@ function formatRow(a) {
 function runHistory(opts = {}) {
   const dir = cwd();
   if (!exists(join(dir, ARCH_DIR9))) {
-    console.error("No architecture/ directory found. Run `kaddo init` first.");
+    console.error("No knowledge/ directory found. Run `kaddo init` first.");
     process.exit(1);
   }
   let artifacts = readArtifacts(join(dir, ARCH_DIR9)).filter(
@@ -5407,7 +5645,7 @@ function runAdd(moduleName, dir = cwd()) {
 
 // src/core/ownership-suggest.ts
 import matter5 from "gray-matter";
-var WORK_ITEMS_DIR3 = "architecture/work-items";
+var WORK_ITEMS_DIR3 = "knowledge/delivery/work-items";
 var SCAN_PATH = ".kaddo/scan.json";
 function toStringArray3(value) {
   return Array.isArray(value) ? value.map((v) => String(v)).filter(Boolean) : [];
@@ -5648,7 +5886,7 @@ ${globs.map((g) => `  - ${g}`).join("\n")}`);
 
 // src/commands/module-descriptor.ts
 import { parse as parseYaml11, stringify as stringifyYaml4 } from "yaml";
-var DESCRIPTOR_PATH2 = "architecture/module.yml";
+var DESCRIPTOR_PATH2 = "knowledge/module.yml";
 function readDescriptor(dir) {
   const path6 = join(dir, DESCRIPTOR_PATH2);
   if (!exists(path6)) return null;
@@ -5673,7 +5911,7 @@ async function runModuleDescriptor(opts) {
     return;
   }
   intro2("kaddo module --init");
-  log2.info("Creates architecture/module.yml \u2014 declares this repository's identity for multirepo contexts.");
+  log2.info("Creates knowledge/module.yml \u2014 declares this repository's identity for multirepo contexts.");
   const name = await text2({
     message: "Module name (this repository)",
     placeholder: "e.g. payments-service",
@@ -5722,7 +5960,7 @@ async function runModuleDescriptor(opts) {
   };
   writeDescriptor(dir, descriptor);
   log2.success(`Created ${DESCRIPTOR_PATH2}`);
-  outro2(`Module descriptor ready. Share architecture/module.yml with dependent repositories.`);
+  outro2(`Module descriptor ready. Share knowledge/module.yml with dependent repositories.`);
 }
 function printDescriptor(d) {
   console.log("");
@@ -5888,7 +6126,7 @@ ${QUALITY}
 - [ ] Capabilities describe outcomes, not implementation.
 - [ ] Each capability cites evidence or is flagged as an assumption.
 `;
-var KNOWLEDGE = `---
+var KNOWLEDGE2 = `---
 type: current-state
 updated_at: YYYY-MM-DD
 ---
@@ -6414,13 +6652,363 @@ ${QUALITY}
 - [ ] Candidates state value and risk.
 - [ ] Marked as candidates, not decisions.
 `;
+var BUSINESS_PRODUCT_BRIEF = `---
+type: product-brief
+status: draft
+---
+
+# Product Brief
+
+> Created by \`kaddo bootstrap\`. Refine with the business-agent. Mark unknowns as TBD.
+
+## What is this product?
+
+TBD
+
+## Problem it solves
+
+TBD
+
+## Target users
+
+TBD
+
+## Value proposition
+
+TBD
+
+## Out of scope (for the MVP)
+
+- TBD
+
+## Assumptions
+
+- ...
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] The product can be described in one paragraph.
+- [ ] The MVP boundary is explicit.
+`;
+var BUSINESS_PROBLEM = `---
+type: problem
+status: draft
+---
+
+# Problem Statement
+
+> Refine with the business-agent. Do not invent facts.
+
+## Problem
+
+TBD
+
+## Who has it
+
+TBD
+
+## Why it matters now
+
+TBD
+
+## Current alternatives
+
+- TBD
+
+## Assumptions
+
+- ...
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] The problem is stated without assuming the solution.
+- [ ] The affected users are named.
+`;
+var BUSINESS_USERS = `---
+type: users
+status: draft
+---
+
+# Users & Personas
+
+> Refine with the business-agent.
+
+## Primary users
+
+- TBD
+
+## Secondary users
+
+- TBD
+
+## Needs & goals
+
+- TBD
+
+## Assumptions
+
+- ...
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] Each persona has a goal, not just a label.
+- [ ] Primary vs secondary users are distinguished.
+`;
+var BUSINESS_VALUE_PROPOSITION = `---
+type: value-proposition
+status: draft
+---
+
+# Value Proposition
+
+> Refine with the business-agent.
+
+## For whom
+
+TBD
+
+## What we offer
+
+TBD
+
+## Why it is better / different
+
+TBD
+
+## Assumptions
+
+- ...
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] The value is specific, not generic.
+- [ ] It maps to a real user need.
+`;
+var BUSINESS_RULES = `---
+type: business-rules
+status: draft
+---
+
+# Business Rules
+
+> Refine with the business-agent. These are product rules, not implementation details.
+
+## Core rules
+
+- TBD
+
+## Edge cases
+
+- TBD
+
+## Assumptions
+
+- ...
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] Rules are testable statements.
+- [ ] No implementation detail leaks in.
+`;
+var BUSINESS_CONSTRAINTS = `---
+type: constraints
+status: draft
+---
+
+# Constraints
+
+> Refine with the business-agent.
+
+## Business constraints
+
+- TBD
+
+## Regulatory / compliance
+
+- TBD
+
+## Time / budget / team
+
+- TBD
+
+## Assumptions
+
+- ...
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] Constraints are real, not aspirational.
+- [ ] Hard limits are separated from preferences.
+`;
+var BUSINESS_GLOSSARY = `---
+type: glossary
+status: draft
+---
+
+# Glossary
+
+> Refine with the business-agent. One shared vocabulary avoids ambiguity.
+
+| Term | Definition |
+|---|---|
+| TBD | TBD |
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] Each term has a single agreed definition.
+- [ ] Ambiguous terms are flagged.
+`;
+var QUALITY_ATTRIBUTES = `---
+type: quality-attributes
+status: draft
+---
+
+# Quality Attributes
+
+> Created by \`kaddo bootstrap\`. Refine with the bootstrap-agent. Prioritize honestly.
+
+## What matters most
+
+- TBD (e.g. reliability, performance, security, maintainability, cost)
+
+## Trade-offs accepted
+
+- TBD
+
+## Measurable targets (if known)
+
+- TBD
+
+## Assumptions
+
+- ...
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] Attributes are prioritized, not all "high".
+- [ ] Trade-offs are explicit.
+`;
+var CODEBASE_FOUNDATION = `---
+type: codebase-foundation
+status: draft
+---
+
+# Codebase Foundation
+
+> Created by \`kaddo bootstrap\`. Refine with the codebase-agent.
+> This describes the intended base \u2014 it does **not** generate code.
+
+## Suggested structure
+
+TBD
+
+## Initial modules / boundaries
+
+- TBD
+
+## Conventions
+
+- TBD
+
+## Git strategy
+
+See \`knowledge/tech/git-strategy.md\`.
+
+## Minimum criteria to start development
+
+- [ ] TBD
+
+## Assumptions
+
+- ...
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] Structure follows the business and architecture, not a framework default.
+- [ ] No production code is described here \u2014 only the foundation.
+`;
+var BOOTSTRAP_SUMMARY = `---
+type: bootstrap-summary
+status: draft
+---
+
+# Bootstrap Summary
+
+> Created by \`kaddo bootstrap\`. Index of the initial knowledge base and next steps.
+
+## Layers
+
+- **Business** \u2014 \`knowledge/business/\`
+- **Architecture** \u2014 capabilities, quality-attributes, stack, current-state, decisions
+- **Codebase** \u2014 codebase-foundation, standards, git-strategy
+- **Development** \u2014 roadmap, work-items
+
+## Status
+
+- [ ] Business defined
+- [ ] Initial architecture proposed
+- [ ] Codebase foundation drafted
+- [ ] Roadmap and first Work Items prepared
+
+## Next steps
+
+1. Run \`kaddo context\` and \`kaddo add agents\`.
+2. Refine the artifacts with the business-agent, bootstrap-agent and
+   codebase-agent in your LLM.
+3. Run \`kaddo create --from roadmap\` to create the first Work Items.
+
+## Open questions
+
+- ...
+
+${QUALITY}
+
+- [ ] Every generated artifact is listed.
+- [ ] The next step is clear.
+`;
 var KADDO_TEMPLATES = [
   // core
   {
     id: "work-item",
     name: "Work Item",
-    category: "core",
-    outputPath: "architecture/work-items/",
+    category: "delivery",
+    outputPath: "knowledge/delivery/work-items/",
     description: "Smallest traceable unit of product evolution.",
     whenToUse: "When you start any change (feature, bugfix, hotfix, spike).",
     relatedCommand: "kaddo create",
@@ -6430,8 +7018,8 @@ var KADDO_TEMPLATES = [
   {
     id: "roadmap",
     name: "Roadmap",
-    category: "core",
-    outputPath: "architecture/roadmap.md",
+    category: "delivery",
+    outputPath: "knowledge/delivery/roadmap.md",
     description: "Initiatives and candidate work items for human review.",
     whenToUse: "When planning what to build next and why.",
     relatedCommand: "kaddo create --from roadmap",
@@ -6441,8 +7029,8 @@ var KADDO_TEMPLATES = [
   {
     id: "capabilities",
     name: "Capabilities",
-    category: "core",
-    outputPath: "architecture/capabilities.md",
+    category: "product",
+    outputPath: "knowledge/product/capabilities.md",
     description: "What the system can do from the product point of view.",
     whenToUse: "When mapping product capabilities to the system.",
     relatedAgent: "capability-agent",
@@ -6451,19 +7039,97 @@ var KADDO_TEMPLATES = [
   {
     id: "knowledge",
     name: "Knowledge (Current State)",
-    category: "core",
-    outputPath: "architecture/knowledge.md",
+    category: "tech",
+    outputPath: "knowledge/knowledge.md",
     description: "What is true about the product right now.",
     whenToUse: "Created by `kaddo init`; keep it current as the product evolves.",
     relatedCommand: "kaddo init",
-    content: KNOWLEDGE
+    content: KNOWLEDGE2
+  },
+  // business (bootstrap)
+  {
+    id: "business-product-brief",
+    name: "Product Brief",
+    category: "product",
+    outputPath: "knowledge/product/product-brief.md",
+    description: "The product in one page: problem, users, value, MVP boundary.",
+    whenToUse: "At the start of a new project (kaddo bootstrap).",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "business-agent",
+    content: BUSINESS_PRODUCT_BRIEF
+  },
+  {
+    id: "business-problem",
+    name: "Problem Statement",
+    category: "business",
+    outputPath: "knowledge/business/problem.md",
+    description: "The problem the product solves, without assuming the solution.",
+    whenToUse: "When defining a new project (kaddo bootstrap).",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "business-agent",
+    content: BUSINESS_PROBLEM
+  },
+  {
+    id: "business-users",
+    name: "Users & Personas",
+    category: "business",
+    outputPath: "knowledge/business/users.md",
+    description: "Primary and secondary users with goals.",
+    whenToUse: "When defining a new project (kaddo bootstrap).",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "business-agent",
+    content: BUSINESS_USERS
+  },
+  {
+    id: "business-value-proposition",
+    name: "Value Proposition",
+    category: "business",
+    outputPath: "knowledge/business/value-proposition.md",
+    description: "For whom, what we offer and why it is better.",
+    whenToUse: "When defining a new project (kaddo bootstrap).",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "business-agent",
+    content: BUSINESS_VALUE_PROPOSITION
+  },
+  {
+    id: "business-rules",
+    name: "Business Rules",
+    category: "business",
+    outputPath: "knowledge/business/business-rules.md",
+    description: "Product rules as testable statements.",
+    whenToUse: "When defining a new project (kaddo bootstrap).",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "business-agent",
+    content: BUSINESS_RULES
+  },
+  {
+    id: "business-constraints",
+    name: "Business Constraints",
+    category: "business",
+    outputPath: "knowledge/business/constraints.md",
+    description: "Business, regulatory and resource constraints.",
+    whenToUse: "When defining a new project (kaddo bootstrap).",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "business-agent",
+    content: BUSINESS_CONSTRAINTS
+  },
+  {
+    id: "business-glossary",
+    name: "Glossary",
+    category: "business",
+    outputPath: "knowledge/business/glossary.md",
+    description: "Shared vocabulary for the project.",
+    whenToUse: "When defining a new project (kaddo bootstrap).",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "business-agent",
+    content: BUSINESS_GLOSSARY
   },
   // architecture
   {
     id: "current-state",
     name: "Current State",
-    category: "architecture",
-    outputPath: "architecture/current-state.md",
+    category: "tech",
+    outputPath: "knowledge/tech/current-state.md",
     description: "Reconstructed architecture baseline.",
     whenToUse: "When establishing the architecture baseline of an existing system.",
     relatedAgent: "architecture-agent",
@@ -6472,8 +7138,8 @@ var KADDO_TEMPLATES = [
   {
     id: "architecture-notes",
     name: "Architecture Notes",
-    category: "architecture",
-    outputPath: "architecture/architecture-notes.md",
+    category: "tech",
+    outputPath: "knowledge/tech/architecture-notes.md",
     description: "Working notes on architecture topics not yet decided.",
     whenToUse: "When exploring an architecture topic before it becomes an ADR.",
     content: ARCHITECTURE_NOTES
@@ -6481,18 +7147,51 @@ var KADDO_TEMPLATES = [
   {
     id: "decision-candidates",
     name: "Decision Candidates",
-    category: "architecture",
-    outputPath: "architecture/decision-candidates.md",
+    category: "tech",
+    outputPath: "knowledge/tech/decision-candidates.md",
     description: "Candidate architecture decisions for human review.",
     whenToUse: "When surfacing decisions that may become ADRs.",
     relatedAgent: "adr-agent",
     content: DECISION_CANDIDATES
   },
+  {
+    id: "quality-attributes",
+    name: "Quality Attributes",
+    category: "tech",
+    outputPath: "knowledge/tech/quality-attributes.md",
+    description: "Prioritized quality attributes and accepted trade-offs.",
+    whenToUse: "During bootstrap, to record what matters most technically.",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "bootstrap-agent",
+    content: QUALITY_ATTRIBUTES
+  },
+  {
+    id: "codebase",
+    name: "Codebase Foundation",
+    category: "tech",
+    outputPath: "knowledge/tech/codebase.md",
+    description: "Intended codebase structure and conventions (no source code).",
+    whenToUse: "During bootstrap, before writing code.",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "codebase-agent",
+    content: CODEBASE_FOUNDATION
+  },
+  {
+    id: "bootstrap-summary",
+    name: "Bootstrap Summary",
+    category: "tech",
+    outputPath: "knowledge/bootstrap-summary.md",
+    description: "Index of the initial knowledge base and next steps.",
+    whenToUse: "Generated by kaddo bootstrap.",
+    relatedCommand: "kaddo bootstrap",
+    relatedAgent: "bootstrap-agent",
+    content: BOOTSTRAP_SUMMARY
+  },
   {
     id: "adr",
     name: "ADR",
-    category: "architecture",
-    outputPath: "architecture/decisions/",
+    category: "tech",
+    outputPath: "knowledge/tech/decisions/",
     description: "A single architecture decision record.",
     whenToUse: "When recording a significant, accepted architecture decision.",
     relatedCommand: "kaddo create adr",
@@ -6503,7 +7202,7 @@ var KADDO_TEMPLATES = [
     id: "module-design",
     name: "Module Design",
     category: "module",
-    outputPath: "architecture/modules/<id>/module-design.md",
+    outputPath: "knowledge/tech/modules/<id>/module-design.md",
     description: "A module's purpose, boundaries and dependencies.",
     whenToUse: "After mapping a secondary repo as a module.",
     relatedCommand: "kaddo modules map",
@@ -6514,7 +7213,7 @@ var KADDO_TEMPLATES = [
     id: "module-stack",
     name: "Module Stack",
     category: "module",
-    outputPath: "architecture/modules/<id>/stack.md",
+    outputPath: "knowledge/tech/modules/<id>/stack.md",
     description: "A module's technology stack.",
     whenToUse: "To document the stack of a specific module.",
     relatedAgent: "stack-agent",
@@ -6524,7 +7223,7 @@ var KADDO_TEMPLATES = [
     id: "module-security",
     name: "Module Security",
     category: "module",
-    outputPath: "architecture/modules/<id>/security.md",
+    outputPath: "knowledge/tech/modules/<id>/security.md",
     description: "A module's security considerations.",
     whenToUse: "To document security concerns specific to a module.",
     relatedAgent: "security-agent",
@@ -6534,7 +7233,7 @@ var KADDO_TEMPLATES = [
     id: "module-standards",
     name: "Module Standards",
     category: "module",
-    outputPath: "architecture/modules/<id>/standards.md",
+    outputPath: "knowledge/tech/modules/<id>/standards.md",
     description: "A module's coding and testing standards.",
     whenToUse: "When a module needs standards beyond the system defaults.",
     relatedAgent: "standards-agent",
@@ -6544,7 +7243,7 @@ var KADDO_TEMPLATES = [
     id: "module-adr",
     name: "Module ADR",
     category: "module",
-    outputPath: "architecture/modules/<id>/adrs/",
+    outputPath: "knowledge/tech/modules/<id>/adrs/",
     description: "A module-scoped architecture decision record.",
     whenToUse: "When a decision affects only one module.",
     content: MODULE_ADR
@@ -6554,7 +7253,7 @@ var KADDO_TEMPLATES = [
     id: "security",
     name: "Security",
     category: "operations",
-    outputPath: "architecture/security.md",
+    outputPath: "knowledge/tech/security.md",
     description: "Global security considerations (no scanning).",
     whenToUse: "To document system-wide security concerns.",
     relatedCommand: "kaddo add security",
@@ -6565,7 +7264,7 @@ var KADDO_TEMPLATES = [
     id: "standards",
     name: "Standards",
     category: "operations",
-    outputPath: "architecture/standards.md",
+    outputPath: "knowledge/tech/standards.md",
     description: "Global lightweight coding/docs/testing standards.",
     whenToUse: "To document system-wide standards.",
     relatedCommand: "kaddo add standards",
@@ -6576,7 +7275,7 @@ var KADDO_TEMPLATES = [
     id: "stack",
     name: "Stack",
     category: "operations",
-    outputPath: "architecture/stack.md",
+    outputPath: "knowledge/tech/stack.md",
     description: "Global technology stack documentation.",
     whenToUse: "To document the system-wide stack.",
     relatedCommand: "kaddo add stack",
@@ -6587,7 +7286,7 @@ var KADDO_TEMPLATES = [
     id: "git-strategy",
     name: "Git Strategy",
     category: "operations",
-    outputPath: "architecture/git-strategy.md",
+    outputPath: "knowledge/tech/git-strategy.md",
     description: "Recommended, customizable Git workflow.",
     whenToUse: "To agree on branching, commits and tagging.",
     relatedCommand: "kaddo add git-strategy",
@@ -6598,7 +7297,7 @@ var KADDO_TEMPLATES = [
     id: "incident",
     name: "Incident",
     category: "operations",
-    outputPath: "architecture/incidents/",
+    outputPath: "knowledge/incidents/",
     description: "A post-incident record.",
     whenToUse: "After a production incident.",
     relatedCommand: "kaddo create incident",
@@ -6608,7 +7307,7 @@ var KADDO_TEMPLATES = [
     id: "runbook",
     name: "Runbook",
     category: "operations",
-    outputPath: "architecture/runbooks/",
+    outputPath: "knowledge/runbooks/",
     description: "How to perform a recurring operational task safely.",
     whenToUse: "For repeatable operational procedures.",
     content: RUNBOOK
@@ -6618,7 +7317,7 @@ var KADDO_TEMPLATES = [
     id: "legacy-risks",
     name: "Legacy Risks",
     category: "legacy",
-    outputPath: "architecture/legacy/risks.md",
+    outputPath: "knowledge/legacy/risks.md",
     description: "High-risk areas before changing legacy code.",
     whenToUse: "Before modifying legacy code.",
     relatedAgent: "legacy-agent",
@@ -6628,7 +7327,7 @@ var KADDO_TEMPLATES = [
     id: "legacy-unknowns",
     name: "Legacy Unknowns",
     category: "legacy",
-    outputPath: "architecture/legacy/unknowns.md",
+    outputPath: "knowledge/legacy/unknowns.md",
     description: "What is not yet understood about the legacy system.",
     whenToUse: "When surfacing gaps in legacy knowledge.",
     relatedAgent: "legacy-agent",
@@ -6638,7 +7337,7 @@ var KADDO_TEMPLATES = [
     id: "modernization-candidates",
     name: "Modernization Candidates",
     category: "legacy",
-    outputPath: "architecture/legacy/modernization-candidates.md",
+    outputPath: "knowledge/legacy/modernization-candidates.md",
     description: "Candidate modernization efforts for human review.",
     whenToUse: "When planning legacy modernization.",
     content: MODERNIZATION_CANDIDATES
@@ -6678,7 +7377,7 @@ function writeModulesDescriptor(dir, descriptor) {
   writeFile(join(dir, DESCRIPTOR_PATH3), stringifyYaml5(descriptor));
 }
 function moduleDir(id) {
-  return `architecture/modules/${id}`;
+  return `knowledge/tech/modules/${id}`;
 }
 function buildModule(input) {
   const id = slugify2(input.name);
@@ -6872,15 +7571,97 @@ function runModulesList(dir = cwd()) {
   console.log("");
 }
 
+// src/commands/bootstrap.ts
+var CONFIG_PATH8 = ".kaddo/config.yml";
+var TARGETS = [
+  // Business — why it exists
+  { layer: "Business", path: "knowledge/business/problem.md", templateId: "business-problem" },
+  { layer: "Business", path: "knowledge/business/users.md", templateId: "business-users" },
+  { layer: "Business", path: "knowledge/business/value-proposition.md", templateId: "business-value-proposition" },
+  { layer: "Business", path: "knowledge/business/constraints.md", templateId: "business-constraints" },
+  { layer: "Business", path: "knowledge/business/business-rules.md", templateId: "business-rules" },
+  // Product — what we build
+  { layer: "Product", path: "knowledge/product/product-brief.md", templateId: "business-product-brief" },
+  { layer: "Product", path: "knowledge/product/capabilities.md", templateId: "capabilities" },
+  // Tech — how we build it
+  { layer: "Tech", path: "knowledge/tech/codebase.md", templateId: "codebase" }
+];
+var BOOTSTRAP_LAYERS = ["Business", "Product", "Tech"];
+function bootstrap(dir) {
+  const written = [];
+  const skipped = [];
+  for (const target of TARGETS) {
+    const full = join(dir, target.path);
+    if (exists(full)) {
+      skipped.push(target.path);
+      continue;
+    }
+    const tpl = getTemplate(target.templateId);
+    const content = tpl ? tpl.content : "";
+    writeFile(full, content.endsWith("\n") ? content : `${content}
+`);
+    written.push(target.path);
+  }
+  return { written, skipped, layers: BOOTSTRAP_LAYERS };
+}
+async function runBootstrap(dir = cwd()) {
+  intro2("kaddo bootstrap");
+  if (!exists(join(dir, CONFIG_PATH8))) {
+    console.error("Kaddo is not initialized in this project.");
+    console.error("Run `kaddo init` first.");
+    process.exit(1);
+  }
+  let state = "unknown";
+  try {
+    const config = loadConfig(dir);
+    state = config?.project.state ?? "unknown";
+  } catch (err) {
+    const message = err instanceof ConfigError ? err.message : String(err);
+    console.error(message);
+    process.exit(1);
+  }
+  log2.info(`Project state: ${state}`);
+  log2.info("Base layers: Business \u2192 Product \u2192 Tech \u2192 Delivery");
+  if (state !== "new") {
+    log2.warn("This project is not marked as new. Bootstrap is designed for new projects.");
+    const ok = await confirm2({ message: "Continue anyway?", initialValue: false });
+    if (!ok) {
+      outro2("Bootstrap cancelled.");
+      return;
+    }
+  }
+  const result = bootstrap(dir);
+  console.log("");
+  console.log("Bootstrap layers:");
+  for (const layer of result.layers) console.log(`  \u2713 ${layer}`);
+  console.log("");
+  if (result.written.length > 0) {
+    console.log("Created:");
+    for (const p2 of result.written) console.log(`  - ${p2}`);
+  }
+  if (result.skipped.length > 0) {
+    console.log("");
+    console.log("Kept existing (skipped):");
+    for (const p2 of result.skipped) console.log(`  - ${p2}`);
+  }
+  console.log("");
+  outro2(
+    "Minimal knowledge base ready (Business \u2192 Product \u2192 Tech). Run `kaddo context` and `kaddo add agents`, then refine with the business-agent, bootstrap-agent and codebase-agent. Roadmap and work items come next under knowledge/delivery/."
+  );
+}
+
 // src/index.ts
 var program = new Command();
-program.name("kaddo").description("Knowledge Driven Development toolkit").version("2.7.0");
+program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.0.0");
 program.command("init").description("Initialize Kaddo in the current project").action(async () => {
   await runInit();
 });
 program.command("scan").description("Detect project stack and suggest domains").action(async () => {
   await runScan();
 });
+program.command("bootstrap").description("Build the initial knowledge base for a new project (Business \u2192 Product \u2192 Tech \u2192 Delivery)").action(async () => {
+  await runBootstrap();
+});
 program.command("create [type]").description("Create a work item (feature, bugfix, hotfix, spike). Use --from roadmap to create from a roadmap candidate.").option("--from <source>", "Create from a source artifact (currently: roadmap)").action(async (type, opts) => {
   await runCreate(type ?? "", opts);
 });
@@ -6925,7 +7706,7 @@ program.command("owners [action]").description("List domain owners, or run `owne
     runOwners(opts);
   }
 });
-program.command("module").description("Show or initialize the multirepo module descriptor (architecture/module.yml)").option("--init", "Create the module descriptor interactively").option("--show", "Print the current module descriptor").action(async (opts) => {
+program.command("module").description("Show or initialize the multirepo module descriptor (knowledge/module.yml)").option("--init", "Create the module descriptor interactively").option("--show", "Print the current module descriptor").action(async (opts) => {
   await runModuleDescriptor(opts);
 });
 var modulesCmd = program.command("modules").description("Map and list secondary repositories as modules of the system (multirepo)");