@yarkingulacti/agentic-scaffold 0.7.0 → 0.7.1

package/README.md

@@ -64,34 +64,44 @@ npx @yarkingulacti/agentic-scaffold --skip-skills --skip-scripts --skip-hooks
 
 # Pre-configure values
 npx @yarkingulacti/agentic-scaffold --project-name "my-app" --issue-tracker github
+
+# Remove all scaffolded files (asks for confirmation)
+npx @yarkingulacti/agentic-scaffold un
+
+# Remove without confirmation
+npx @yarkingulacti/agentic-scaffold un --force
 ```
 
 ## What you get
 
 ```
 project/
-├── AGENTS.md                 # Agent config (entry point for AI agents)
-├── CLAUDE.md                 # Mirror of AGENTS.md
-├── BUSINESS_LOGIC.md         # Shell — fill with your domain
-├── .gitignore
-├── docs/
-│   ├── CODING_PRINCIPLES.md  # Operating rules for code
-│   ├── adr/TEMPLATE.md       # Architecture Decision Record template
-│   ├── agents/
-│   │   ├── domain.md         # How to consume domain docs
-│   │   ├── session-close.md  # Post-coding session workflow
-│   │   ├── issue-tracker.md  # Issue tracker conventions
-│   │   └── triage-labels.md  # Triage status vocabulary
-│   ├── context/
-│   │   ├── INDEX.md          # Section index for CONTEXT.md
-│   │   └── glossary.md       # Ubiquitous language glossary
-│   ├── engineering/README.md
-│   └── product/README.md
-├── .agents/skills/           # Agent skill definitions (21 skills)
-├── .agents/hooks/            # Pre/post lifecycle hooks for agent workflows
-├── scripts/                  # Markdown memory indexing pipeline
-├── .scratchpad/              # Local detailed planning
-└── .history/                 # Shipped work summaries
+├── AGENTS.md -> .agentic-scaffold/AGENTS.md   # Symlink entry point
+├── CLAUDE.md -> .agentic-scaffold/CLAUDE.md   # Symlink entry point
+└── .agentic-scaffold/                          # Single wrapper directory
+    ├── AGENTS.md                 # Agent config (entry point for AI agents)
+    ├── CLAUDE.md                 # Mirror of AGENTS.md
+    ├── BUSINESS_LOGIC.md         # Shell — fill with your domain
+    ├── .gitignore
+    ├── docs/
+    │   ├── CODING_PRINCIPLES.md  # Operating rules for code
+    │   ├── adr/TEMPLATE.md       # Architecture Decision Record template
+    │   ├── agents/
+    │   │   ├── domain.md         # How to consume domain docs
+    │   │   ├── session-close.md  # Post-coding session workflow
+    │   │   ├── issue-tracker.md  # Issue tracker conventions
+    │   │   └── triage-labels.md  # Triage status vocabulary
+    │   ├── context/
+    │   │   ├── INDEX.md          # Section index for CONTEXT.md
+    │   │   └── glossary.md       # Ubiquitous language glossary
+    │   ├── engineering/README.md
+    │   └── product/README.md
+    ├── .agents/
+    │   ├── skills/               # Agent skill definitions (22 skills)
+    │   └── hooks/                # Pre/post lifecycle hooks
+    ├── scripts/                  # Markdown memory indexing pipeline
+    ├── .scratchpad/              # Local detailed planning
+    └── .history/                 # Shipped work summaries
 ```
 
 ## Auto-detection
@@ -126,6 +136,12 @@ CLI flags.
 - **`--skip-hooks` flag** — skip the hooks component group.
 - **98 tests** — detection, scaffolding, CLI, and hooks tested end-to-end.
 
+## New in v0.6
+
+- **Interactive mode redesign** — shows detected project profile before prompts, pre-fills prompts with detected values, and per-file conflict resolver that asks before overwriting existing files.
+- **MEMORY.md golden rules** — feature branches mandatory for new features, every release gets a version tag.
+- **Per-file conflict resolution** — `askOverwrite()` prompt lets you decide for each existing file during scaffolding.
+
 ## New in v0.5
 
 - **`fill-docs` skill** — new agent skill that interviews you to complete placeholder content in BUSINESS_LOGIC.md, glossary, and other scaffolded docs.
@@ -154,12 +170,26 @@ CLI flags.
 
 ## After scaffolding
 
-1. Fill in `BUSINESS_LOGIC.md` with your product domain.
+1. Fill in `.agentic-scaffold/BUSINESS_LOGIC.md` with your product domain.
 2. Run `npm install` / `pnpm install` for your project's actual dependencies.
 3. `python3 -m venv .venv && pip install sqlite-vec` if you want vector memory.
-4. Install the skills in your AI tool (e.g. opencode) — each `.agents/skills/*/SKILL.md` is self-contained.
-5. Customize `docs/agents/triage-labels.md` to match your tracker's vocabulary.
-6. Use the `fill-docs` skill (`.agents/skills/fill-docs/SKILL.md`) to complete scaffolded documentation.
+4. Install the skills in your AI tool (e.g. opencode) — each `.agentic-scaffold/.agents/skills/*/SKILL.md` is self-contained.
+5. Customize `.agentic-scaffold/docs/agents/triage-labels.md` to match your tracker's vocabulary.
+6. Use the `fill-docs` skill (`.agentic-scaffold/.agents/skills/fill-docs/SKILL.md`) to complete scaffolded documentation.
+
+## Unscaffold
+
+Remove all scaffolded files in one command:
+
+```bash
+# Interactive (asks for confirmation)
+npx @yarkingulacti/agentic-scaffold un
+
+# Non-interactive
+npx @yarkingulacti/agentic-scaffold un --force
+```
+
+This removes the entire `.agentic-scaffold/` directory and the root-level symlinks (AGENTS.md, CLAUDE.md). Your project files are left untouched.
 
 ## Open source
 

package/bin/index.js

@@ -2,92 +2,113 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { scaffold } from "../src/scaffold.js";
+import { unscaffold } from "../src/unscaffold.js";
 
-const argv = yargs(hideBin(process.argv))
-  .usage("$0 [options]")
-  .epilogue(
-    "Tiers:\n" +
-    "  Zero-config   Run with no flags \u2014 auto-detect project, scaffold only\n" +
-    "                what\u2019s missing. Never overwrites existing files.\n" +
-    "  Flag mode     Override auto-detection with --package-manager,\n" +
-    "                --ci-provider, --ai-tools, etc. Add --force to overwrite.\n" +
-    "  Interactive   Run with -i / --interactive for step-by-step prompts."
-  )
-  .example("$0", "Zero-config: auto-detect and scaffold missing files")
-  .example("$0 --force", "Force overwrite existing files")
-  .example("$0 --ci-provider github", "Override auto-detected CI provider")
-  .example("$0 --ai-tools opencode,cursor", "Generate configs for specific AI tools")
-  .example("$0 -i", "Interactive mode with prompts")
-  .option("interactive", {
-    alias: "i",
-    type: "boolean",
-    description: "Run in interactive mode with prompts",
-    default: false,
-  })
-  .option("target", {
-    alias: "t",
-    type: "string",
-    description: "Target directory (default: current working directory)",
-    default: process.cwd(),
-  })
-  .option("only", {
-    type: "string",
-    description: "Comma-separated component groups to include: docs,scripts,skills,all",
-    default: "all",
-  })
-      .option("skip-skills", {
-        type: "boolean",
-        description: "Skip agent skill definitions",
-      })
-      .option("skip-hooks", {
-        type: "boolean",
-        description: "Skip agent lifecycle hook templates",
-      })
-  .option("skip-scripts", {
-    type: "boolean",
-    description: "Skip memory scripts",
-    default: false,
-  })
-  .option("skip-docs", {
-    type: "boolean",
-    description: "Skip docs folder",
-    default: false,
-  })
-  .option("project-name", {
-    type: "string",
-    description: "Project name (used in generated files)",
-  })
-  .option("issue-tracker", {
-    type: "string",
-    choices: ["linear", "github", "both"],
-    description: "Issue tracker type",
-  })
-  .option("force", {
-    alias: "f",
-    type: "boolean",
-    description: "Overwrite existing files",
-    default: false,
-  })
-  .option("package-manager", {
-    type: "string",
-    choices: ["npm", "yarn", "pnpm", "pip", "poetry", "go-mod", "cargo"],
-    description: "Package manager (overrides auto-detection)",
-  })
-  .option("ci-provider", {
-    type: "string",
-    choices: ["github", "gitlab", "circleci"],
-    description: "CI provider (overrides auto-detection)",
-  })
-  .option("ai-tools", {
-    type: "string",
-    description: "Comma-separated AI tools to configure: opencode,cursor,copilot",
-  })
-  .option("script-language", {
-    type: "string",
-    choices: ["python", "node", "docker"],
-    description: "Memory script language (overrides auto-detection)",
-  })
+function scaffoldBuilder(y) {
+  return y
+    .epilogue(
+      "Tiers:\n" +
+      "  Zero-config   Run with no flags \u2014 auto-detect project, scaffold only\n" +
+      "                what\u2019s missing. Never overwrites existing files.\n" +
+      "  Flag mode     Override auto-detection with --package-manager,\n" +
+      "                --ci-provider, --ai-tools, etc. Add --force to overwrite.\n" +
+      "  Interactive   Run with -i / --interactive for step-by-step prompts."
+    )
+    .example("$0", "Zero-config: auto-detect and scaffold missing files")
+    .example("$0 --force", "Force overwrite existing files")
+    .example("$0 --ci-provider github", "Override auto-detected CI provider")
+    .example("$0 --ai-tools opencode,cursor", "Generate configs for specific AI tools")
+    .example("$0 -i", "Interactive mode with prompts")
+    .option("interactive", {
+      alias: "i",
+      type: "boolean",
+      description: "Run in interactive mode with prompts",
+      default: false,
+    })
+    .option("target", {
+      alias: "t",
+      type: "string",
+      description: "Target directory (default: current working directory)",
+      default: process.cwd(),
+    })
+    .option("only", {
+      type: "string",
+      description: "Comma-separated component groups to include: docs,scripts,skills,all",
+      default: "all",
+    })
+    .option("skip-skills", {
+      type: "boolean",
+      description: "Skip agent skill definitions",
+    })
+    .option("skip-hooks", {
+      type: "boolean",
+      description: "Skip agent lifecycle hook templates",
+    })
+    .option("skip-scripts", {
+      type: "boolean",
+      description: "Skip memory scripts",
+      default: false,
+    })
+    .option("skip-docs", {
+      type: "boolean",
+      description: "Skip docs folder",
+      default: false,
+    })
+    .option("project-name", {
+      type: "string",
+      description: "Project name (used in generated files)",
+    })
+    .option("issue-tracker", {
+      type: "string",
+      choices: ["linear", "github", "both"],
+      description: "Issue tracker type",
+    })
+    .option("force", {
+      alias: "f",
+      type: "boolean",
+      description: "Overwrite existing files",
+      default: false,
+    })
+    .option("package-manager", {
+      type: "string",
+      choices: ["npm", "yarn", "pnpm", "pip", "poetry", "go-mod", "cargo"],
+      description: "Package manager (overrides auto-detection)",
+    })
+    .option("ci-provider", {
+      type: "string",
+      choices: ["github", "gitlab", "circleci"],
+      description: "CI provider (overrides auto-detection)",
+    })
+    .option("ai-tools", {
+      type: "string",
+      description: "Comma-separated AI tools to configure: opencode,cursor,copilot",
+    })
+    .option("script-language", {
+      type: "string",
+      choices: ["python", "node", "docker"],
+      description: "Memory script language (overrides auto-detection)",
+    });
+}
+
+function unBuilder(y) {
+  return y
+    .option("target", {
+      alias: "t",
+      type: "string",
+      description: "Target directory (default: current working directory)",
+      default: process.cwd(),
+    })
+    .option("force", {
+      alias: "f",
+      type: "boolean",
+      description: "Remove without confirmation",
+      default: false,
+    });
+}
+
+yargs(hideBin(process.argv))
+  .command(["$0", "scaffold"], "Scaffold agentic configuration into a project", scaffoldBuilder, (argv) => scaffold(argv))
+  .command("un", "Remove scaffolded files from a project", unBuilder, (argv) => unscaffold(argv))
+  .demandCommand(1, "Use --help to see available commands")
   .help()
   .parse();
-
-await scaffold(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkingulacti/agentic-scaffold",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Scaffold agentic development documentation & configuration into any project",
   "type": "module",
   "bin": {

package/src/scaffold.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, symlinkSync } from "node:fs";
 import { readdirSync, statSync, copyFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -23,6 +23,7 @@ function resolveConfig(argv) {
 
   const config = {
     target,
+    scaffoldDir: join(target, ".agentic-scaffold"),
     projectName: argv.projectName ?? profile.projectName ?? (target.split("/").filter(Boolean).pop() ?? "project"),
     projectDescription: argv.projectDescription ?? profile.projectDescription ?? DEFAULTS.projectDescription,
     languages: profile.languages,
@@ -54,9 +55,9 @@ function resolveIncludes(argv) {
 const ISSUE_TRACKER_DOCS = {
   linear: {
     name: "Linear",
-    description: "Short implementation records live in Linear. Local, detailed planning lives in `.scratchpad/<feature>/`. See `docs/agents/issue-tracker.md`.",
+    description: "Short implementation records live in Linear. Local, detailed planning lives in `.agentic-scaffold/.scratchpad/<feature>/`. See `.agentic-scaffold/docs/agents/issue-tracker.md`.",
     trackerDoc: "Linear",
-    short: "Short issue records live in Linear. Local detailed planning lives in `.scratchpad/`.",
+    short: "Short issue records live in Linear. Local detailed planning lives in `.agentic-scaffold/.scratchpad/`.",
     statusTable: `| Label | Status string | Meaning |
 |-------|--------------|---------|
 | needs-triage | \`needs-triage\` | Maintainer needs to evaluate this issue |
@@ -70,7 +71,7 @@ LINEAR_PROJECT_ID=`,
   },
   github: {
     name: "GitHub Issues",
-    description: "Short implementation records live in GitHub Issues. Local, detailed planning lives in `.scratchpad/<feature>/`. See `docs/agents/issue-tracker.md`.",
+    description: "Short implementation records live in GitHub Issues. Local, detailed planning lives in `.agentic-scaffold/.scratchpad/<feature>/`. See `.agentic-scaffold/docs/agents/issue-tracker.md`.",
     trackerDoc: "GitHub Issues",
     short: "Short issue records live in GitHub Issues. Local detailed planning lives in `.scratchpad/`.",
     statusTable: `| Label | Meaning |
@@ -87,13 +88,13 @@ LINEAR_PROJECT_ID=`,
 
 function buildIncompleteFiles(config) {
   const files = [
-    { file: "BUSINESS_LOGIC.md", sections: "Core Domain Concepts, Non-Negotiable Rules, Architecture Decisions" },
+    { file: ".agentic-scaffold/BUSINESS_LOGIC.md", sections: "Core Domain Concepts, Non-Negotiable Rules, Architecture Decisions" },
   ];
   if (config.include.has("docs")) {
     files.push(
-      { file: "docs/context/glossary.md", sections: "domain term definitions" },
-      { file: "docs/product/README.md", sections: "product spec descriptions" },
-      { file: "docs/engineering/README.md", sections: "implementation conventions" },
+      { file: ".agentic-scaffold/docs/context/glossary.md", sections: "domain term definitions" },
+      { file: ".agentic-scaffold/docs/product/README.md", sections: "product spec descriptions" },
+      { file: ".agentic-scaffold/docs/engineering/README.md", sections: "implementation conventions" },
     );
   }
   return files;
@@ -117,7 +118,7 @@ function buildHandlebars(config) {
   return {
     projectName: config.projectName,
     projectDescription: config.projectDescription,
-    scriptsDir: "scripts",
+    scriptsDir: ".agentic-scaffold/scripts",
     issueTrackerName: tracker.name,
     issueTrackerDescription: tracker.description,
     issueTrackerShort: tracker.short,
@@ -216,48 +217,76 @@ async function renderDir(srcDir, destDir, data, options = {}) {
   return results;
 }
 
+const SCAFFOLD_DIR_NAME = ".agentic-scaffold";
+
+function scaffoldDir(config) {
+  return config.scaffoldDir;
+}
+
 async function scaffoldRoot(config, hbData, extraOpts = {}) {
   const rootSrc = join(TEMPLATES_DIR, "root");
-  const rootDest = config.target;
+  const rootDest = scaffoldDir(config);
   return renderDir(rootSrc, rootDest, hbData, { force: config.force, interactive: config.interactive, ...extraOpts });
 }
 
 async function scaffoldDocs(config, hbData, extraOpts = {}) {
   const docsSrc = join(TEMPLATES_DIR, "docs");
-  const docsDest = join(config.target, "docs");
+  const docsDest = join(scaffoldDir(config), "docs");
   return renderDir(docsSrc, docsDest, hbData, { force: config.force, interactive: config.interactive, ...extraOpts });
 }
 
 async function scaffoldScripts(config, hbData, extraOpts = {}) {
   const scriptsSrc = join(TEMPLATES_DIR, "scripts");
-  const scriptsDest = join(config.target, "scripts");
+  const scriptsDest = join(scaffoldDir(config), "scripts");
   return renderDir(scriptsSrc, scriptsDest, hbData, { force: config.force, interactive: config.interactive, ...extraOpts });
 }
 
 async function scaffoldSkills(config, extraOpts = {}) {
   const skillsSrc = join(TEMPLATES_DIR, "skills");
-  const skillsDest = join(config.target, ".agents", "skills");
+  const skillsDest = join(scaffoldDir(config), ".agents", "skills");
   return copyStaticDir(skillsSrc, skillsDest, { force: config.force, interactive: config.interactive, ...extraOpts });
 }
 
 async function scaffoldHooks(config, hbData, extraOpts = {}) {
   const hooksSrc = join(TEMPLATES_DIR, "hooks");
-  const hooksDest = join(config.target, ".agents", "hooks");
+  const hooksDest = join(scaffoldDir(config), ".agents", "hooks");
   return renderDir(hooksSrc, hooksDest, hbData, { force: config.force, interactive: config.interactive, ...extraOpts });
 }
 
 async function scaffoldScratchpad(config, extraOpts = {}) {
   const src = join(TEMPLATES_DIR, "scratchpad");
-  const dest = join(config.target, ".scratchpad");
+  const dest = join(scaffoldDir(config), ".scratchpad");
   return copyStaticDir(src, dest, { force: config.force, interactive: config.interactive, ...extraOpts });
 }
 
 async function scaffoldHistory(config, extraOpts = {}) {
   const src = join(TEMPLATES_DIR, "history");
-  const dest = join(config.target, ".history");
+  const dest = join(scaffoldDir(config), ".history");
   return copyStaticDir(src, dest, { force: config.force, interactive: config.interactive, ...extraOpts });
 }
 
+function createSymlinks(config) {
+  const links = [
+    ["AGENTS.md", ".agentic-scaffold/AGENTS.md"],
+    ["CLAUDE.md", ".agentic-scaffold/CLAUDE.md"],
+  ];
+  const created = [];
+  for (const [name, target] of links) {
+    const linkPath = join(config.target, name);
+    if (existsSync(linkPath)) {
+      created.push("skipped-existing");
+      continue;
+    }
+    try {
+      symlinkSync(target, linkPath);
+      created.push("written");
+    } catch {
+      created.push("skipped-existing");
+    }
+  }
+  return created;
+}
+
 function countTemplateFiles(config) {
   const dirs = [
     join(TEMPLATES_DIR, "root"),
@@ -324,6 +353,8 @@ export async function scaffold(argv) {
   results.push(...(await scaffoldScratchpad(config, tickOpts)));
   results.push(...(await scaffoldHistory(config, tickOpts)));
 
+  results.push(...(await createSymlinks(config)));
+
   process.stdout.write("\r".padEnd(60) + "\r");
 
   const written = results.filter((r) => r === "written").length;
@@ -345,7 +376,7 @@ export async function scaffold(argv) {
     }
     if (config.include.has("skills")) {
       console.log(`\n ${style.dim("Agent skill available to help:")}`);
-      console.log(`   .agents/skills/fill-docs/SKILL.md`);
+      console.log(`   .agentic-scaffold/.agents/skills/fill-docs/SKILL.md`);
       console.log(`   ${style.dim("Invoke it with your AI agent to fill in these files conversationally.")}`);
     }
   }

package/src/unscaffold.js

@@ -0,0 +1,84 @@
+import { existsSync, readdirSync, lstatSync, readlinkSync, rmSync } from "node:fs";
+import { join, relative } from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { infoBox, summaryLine, style } from "./ui.js";
+
+const SCAFFOLD_DIR = ".agentic-scaffold";
+
+function findScaffoldFiles(target) {
+  const scaffoldPath = join(target, SCAFFOLD_DIR);
+  if (!existsSync(scaffoldPath)) return null;
+
+  const files = [];
+  collectFiles(scaffoldPath, files);
+  return { scaffoldPath, files };
+}
+
+function collectFiles(dir, files) {
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    const stat = lstatSync(full);
+    if (stat.isDirectory()) {
+      files.push({ path: full, type: "dir" });
+      collectFiles(full, files);
+    } else {
+      files.push({ path: full, type: "file" });
+    }
+  }
+}
+
+function findSymlinks(target) {
+  const links = [];
+  for (const name of ["AGENTS.md", "CLAUDE.md"]) {
+    const full = join(target, name);
+    if (!existsSync(full)) continue;
+    const stat = lstatSync(full);
+    if (stat.isSymbolicLink()) {
+      const linkTarget = readlinkSync(full);
+      if (linkTarget.startsWith(SCAFFOLD_DIR)) {
+        links.push(full);
+      }
+    }
+  }
+  return links;
+}
+
+export async function unscaffold(argv) {
+  const target = argv.target || process.cwd();
+  const force = argv.force ?? false;
+
+  const scaffoldData = findScaffoldFiles(target);
+  if (!scaffoldData) {
+    console.log(` ${summaryLine("Nothing to unscaffold — .agentic-scaffold/ not found.", "done")}`);
+    return;
+  }
+
+  const symlinks = findSymlinks(target);
+  const { scaffoldPath, files } = scaffoldData;
+
+  const rows = [
+    ["Target", style.cyan(target)],
+    ["Files to remove", style.cyan(String(files.length))],
+    ["Symlinks to remove", style.cyan(String(symlinks.length))],
+  ];
+  console.log(`\n${infoBox(rows)}`);
+
+  if (!force) {
+    const rl = readline.createInterface({ input, output });
+    const answer = await rl.question(`  Remove .agentic-scaffold/ (${files.length} files, ${symlinks.length} symlinks)? [y/N]: `);
+    rl.close();
+    if (answer.trim().toLowerCase() !== "y") {
+      console.log(` ${summaryLine("Unscaffold cancelled.", "warn")}`);
+      return;
+    }
+  }
+
+  rmSync(scaffoldPath, { recursive: true, force: true });
+
+  for (const link of symlinks) {
+    rmSync(link, { force: true });
+  }
+
+  console.log(` ${summaryLine(`Removed ${files.length} files and ${symlinks.length} symlinks.`, "done")}`);
+}

package/templates/docs/CODING_PRINCIPLES.md

@@ -34,7 +34,7 @@ This is the short repo version for day-to-day implementation by human and AI age
 
 - Is every new file needed for the current task?
 - Is each new abstraction used by real code today?
-- Does the code use project vocabulary from `BUSINESS_LOGIC.md` and `docs/context/glossary.md`?
+- Does the code use project vocabulary from `.agentic-scaffold/BUSINESS_LOGIC.md` and `.agentic-scaffold/docs/context/glossary.md`?
 - Are failures handled near the boundary where they become knowable?
 - Do tests cover the behavior that could regress?
 - Could a simpler function or module solve the same current requirement?

package/templates/docs/agents/domain.md.hbs

@@ -3,28 +3,28 @@
 How the engineering skills should consume this repo's domain documentation when
 exploring the codebase.
 
-This repo uses `BUSINESS_LOGIC.md` as the primary project brain, with `docs/`
-and `docs/adr/` as supporting tracked documentation.
+This repo uses `.agentic-scaffold/BUSINESS_LOGIC.md` as the primary project brain, with `.agentic-scaffold/docs/`
+and `.agentic-scaffold/docs/adr/` as supporting tracked documentation.
 
-Agents must read `BUSINESS_LOGIC.md` first before planning, coding, or creating
-issues. Future task plans must cite the relevant `BUSINESS_LOGIC.md` section.
+Agents must read `.agentic-scaffold/BUSINESS_LOGIC.md` first before planning, coding, or creating
+issues. Future task plans must cite the relevant `.agentic-scaffold/BUSINESS_LOGIC.md` section.
 
 `CONTEXT.md` remains a **verbatim mirror** of the Obsidian vault, regenerated by
-`scripts/sync-context.sh`. Never hand-edit it. Do not read it whole. Use
-`docs/context/INDEX.md` to map your work area to relevant sections.
+`.agentic-scaffold/scripts/sync-context.sh`. Never hand-edit it. Do not read it whole. Use
+`.agentic-scaffold/docs/context/INDEX.md` to map your work area to relevant sections.
 
-When `CONTEXT.md` conflicts with `BUSINESS_LOGIC.md` or an accepted ADR, follow
-`BUSINESS_LOGIC.md` and the accepted ADR. Treat `CONTEXT.md` as historical input
+When `CONTEXT.md` conflicts with `.agentic-scaffold/BUSINESS_LOGIC.md` or an accepted ADR, follow
+`.agentic-scaffold/BUSINESS_LOGIC.md` and the accepted ADR. Treat `CONTEXT.md` as historical input
 until the vault mirror is regenerated.
 
-Glossary terms live in `docs/context/glossary.md`.
+Glossary terms live in `.agentic-scaffold/docs/context/glossary.md`.
 
 ## Before exploring, read these
 
-- **`BUSINESS_LOGIC.md`** — product fundamentals and non-negotiable rules.
-- **`docs/context/INDEX.md`** — pick relevant historical `CONTEXT.md` sections.
+- **`.agentic-scaffold/BUSINESS_LOGIC.md`** — product fundamentals and non-negotiable rules.
+- **`.agentic-scaffold/docs/context/INDEX.md`** — pick relevant historical `CONTEXT.md` sections.
 - **`CONTEXT.md`** — only the sections the index points you to.
-- **`docs/adr/`** — read ADRs that touch the area you're about to work in.
+- **`.agentic-scaffold/docs/adr/`** — read ADRs that touch the area you're about to work in.
 
 If any of these files don't exist, **proceed silently**. Don't flag their
 absence; don't suggest creating them upfront.
@@ -34,17 +34,20 @@ absence; don't suggest creating them upfront.
 ```
 /
 ├── CONTEXT.md
-├── BUSINESS_LOGIC.md
-├── docs/adr/
-│   ├── 0001-example-decision.md
-│   └── 0002-another-decision.md
-└── ...
+├── AGENTS.md -> .agentic-scaffold/AGENTS.md
+├── CLAUDE.md -> .agentic-scaffold/CLAUDE.md
+└── .agentic-scaffold/
+    ├── BUSINESS_LOGIC.md
+    ├── docs/adr/
+    │   ├── 0001-example-decision.md
+    │   └── 0002-another-decision.md
+    └── ...
 ```
 
 ## Use the glossary's vocabulary
 
 When your output names a domain concept, use the term as defined in
-`docs/context/glossary.md`. Don't drift to synonyms the glossary explicitly
+`.agentic-scaffold/docs/context/glossary.md`. Don't drift to synonyms the glossary explicitly
 avoids.
 
 If the concept you need isn't in the glossary yet, that's a signal — either

package/templates/docs/agents/issue-tracker.md.hbs

@@ -5,17 +5,17 @@
 ## Conventions
 
 - Keep {{issueTrackerName}} titles and descriptions short.
-- Put detailed implementation plans in `.scratchpad/<feature-slug>/`.
+- Put detailed implementation plans in `.agentic-scaffold/.scratchpad/<feature-slug>/`.
 - Link the {{issueTrackerName}} issue from the matching scratchpad file.
 - Do not use issue comments as project memory.
-- Shipped work summaries live in `.history/DD.MM.YYYY/README.md`.
+- Shipped work summaries live in `.agentic-scaffold/.history/DD.MM.YYYY/README.md`.
 
 ## When a skill says "publish to the issue tracker"
 
 Create or update the {{issueTrackerName}} issue, then create the matching local
-detail file under `.scratchpad/<feature-slug>/`.
+detail file under `.agentic-scaffold/.scratchpad/<feature-slug>/`.
 
 ## When a skill says "fetch the relevant ticket"
 
-Read the {{issueTrackerName}} issue summary and the matching `.scratchpad/`
+Read the {{issueTrackerName}} issue summary and the matching `.agentic-scaffold/.scratchpad/`
 detail file when one exists.

package/templates/docs/agents/session-close.md.hbs

@@ -5,18 +5,18 @@ handing off.
 
 ## Required Steps
 
-If `.agents/hooks/post-session.md` exists, read and follow it instead of this
+If `.agentic-scaffold/.agents/hooks/post-session.md` exists, read and follow it instead of this
 file — it contains the canonical post-session workflow.
 
 Otherwise, follow the steps below:
 
 1. Run the relevant tests.
 2. Build every touched project when a build command exists.
-3. Create or update `.history/DD.MM.YYYY/README.md` with the master work title,
+3. Create or update `.agentic-scaffold/.history/DD.MM.YYYY/README.md` with the master work title,
    summary, changed files, verification, and remaining risk.
-4. Re-index Markdown memory with `scripts/memory_index.py` so `.history/` is in
+4. Re-index Markdown memory with `.agentic-scaffold/scripts/memory_index.py` so `.agentic-scaffold/.history/` is in
    the SQLite vector database.
-5. Update the related `.scratchpad/` status lines.
+5. Update the related `.agentic-scaffold/.scratchpad/` status lines.
 6. Create a Conventional Commit under the master work title.
 7. Push a `feature/...`, `bugfix/...`, `docs/...`, or similar branch to the
    remote.
@@ -46,5 +46,5 @@ Allowed common types: `feat`, `fix`, `docs`, `refactor`, `test`, `build`,
 ## Blockers
 
 If a step cannot run because the repo has no command, no remote, invalid auth,
-or missing external service, record that in `.history/` and the final response.
+or missing external service, record that in `.agentic-scaffold/.history/` and the final response.
 Do not pretend the step succeeded.

package/templates/docs/context/INDEX.md

@@ -17,7 +17,7 @@ existing ones.
 
 ## Full section map
 
-<!-- Generated by scripts/sync-context.sh -->
+<!-- Generated by .agentic-scaffold/scripts/sync-context.sh -->
 
 ```text
 (populated by sync-context.sh)

package/templates/hooks/post-bugfix.md.hbs

@@ -6,9 +6,9 @@ Fires after a bugfix is delivered.
 
 1. Run the project's test suite to confirm the fix does not regress:
    {{#if packageManager}}   `{{packageManager}} test`{{else}}   `npm test`{{/if}}
-2. Run `.agents/hooks/scripts/post-bugfix.sh` if it exists.
-3. Update `.history/DD.MM.YYYY/README.md` with a summary of the fix.
-4. Update the related `.scratchpad/` status to mark completion.
+2. Run `.agentic-scaffold/.agents/hooks/scripts/post-bugfix.sh` if it exists.
+3. Update `.agentic-scaffold/.history/DD.MM.YYYY/README.md` with a summary of the fix.
+4. Update the related `.agentic-scaffold/.scratchpad/` status to mark completion.
 5. Create a Conventional Commit under the master work title.
 
 ## When to skip

package/templates/hooks/post-feature.md.hbs

@@ -6,10 +6,10 @@ Fires after a feature is delivered by any implementation skill.
 
 1. Run the project's test suite:
    {{#if packageManager}}   `{{packageManager}} test`{{else}}   `npm test`{{/if}}
-2. Run `.agents/hooks/scripts/post-feature.sh` if it exists.
-3. Update `.history/DD.MM.YYYY/README.md` with a summary of shipped work.
-4. Run `scripts/memory_index.py` to keep the vector index current.
-5. Update the related `.scratchpad/` status to mark completion.
+2. Run `.agentic-scaffold/.agents/hooks/scripts/post-feature.sh` if it exists.
+3. Update `.agentic-scaffold/.history/DD.MM.YYYY/README.md` with a summary of shipped work.
+4. Run `.agentic-scaffold/scripts/memory_index.py` to keep the vector index current.
+5. Update the related `.agentic-scaffold/.scratchpad/` status to mark completion.
 6. Create a Conventional Commit under the master work title.
 
 ## When to skip

package/templates/hooks/post-session.md.hbs

@@ -5,13 +5,13 @@ Replaces the legacy session-close workflow.
 
 ## Steps
 
-1. Run `.agents/hooks/scripts/post-session.sh` if it exists.
+1. Run `.agentic-scaffold/.agents/hooks/scripts/post-session.sh` if it exists.
 2. Run all applicable post-* hooks that match the work done:
-   - After feature work: `.agents/hooks/post-feature.md`
-   - After bugfix work: `.agents/hooks/post-bugfix.md`
+   - After feature work: `.agentic-scaffold/.agents/hooks/post-feature.md`
+   - After bugfix work: `.agentic-scaffold/.agents/hooks/post-bugfix.md`
 3. Build every touched project when a build command exists.
-4. Run `scripts/memory_index.py` so `.history/` is in the vector database.
-5. Update all affected `.scratchpad/` status lines.
+4. Run `.agentic-scaffold/scripts/memory_index.py` so `.agentic-scaffold/.history/` is in the vector database.
+5. Update all affected `.agentic-scaffold/.scratchpad/` status lines.
 6. Push the feature/bugfix branch to the remote.
 7. Create a PR, review it, merge it, then delete the PR branch.
 
@@ -30,5 +30,5 @@ Allowed types: `feat`, `fix`, `docs`, `refactor`, `test`, `build`, `ci`, `chore`
 ## Blockers
 
 If a step cannot run because the repo has no command, no remote, invalid
-auth, or missing external service, record that in `.history/` and the final
+auth, or missing external service, record that in `.agentic-scaffold/.history/` and the final
 response. Do not pretend the step succeeded.

package/templates/hooks/pre-feature.md.hbs

@@ -6,10 +6,10 @@ initiates the work.
 ## Steps
 
 1. Read `BUSINESS_LOGIC.md` and any relevant ADR.
-2. Read the issue ticket and matching `.scratchpad/` detail file.
+2. Read the issue ticket and matching `.agentic-scaffold/.scratchpad/` detail file.
 3. If no scratchpad detail exists and the task is complex, create one.
-4. Read `docs/CODING_PRINCIPLES.md` to confirm approach.
-5. Run `.agents/hooks/scripts/pre-feature.sh` if it exists.
+4. Read `.agentic-scaffold/docs/CODING_PRINCIPLES.md` to confirm approach.
+5. Run `.agentic-scaffold/.agents/hooks/scripts/pre-feature.sh` if it exists.
 
 ## When to skip
 

package/templates/root/AGENTS.md.hbs

@@ -4,12 +4,12 @@
 
 ### Project brain
 
-Read `BUSINESS_LOGIC.md` first for product fundamentals, core domain concepts,
+Read `.agentic-scaffold/BUSINESS_LOGIC.md` first for product fundamentals, core domain concepts,
 non-negotiable rules, and decision references. Future task plans must cite the
-relevant `BUSINESS_LOGIC.md` section before implementation.
+relevant `.agentic-scaffold/BUSINESS_LOGIC.md` section before implementation.
 
 `CONTEXT.md` remains a generated historical mirror from the Obsidian vault. Use
-`docs/context/INDEX.md` to locate narrow sections when old context is needed;
+`.agentic-scaffold/docs/context/INDEX.md` to locate narrow sections when old context is needed;
 do not read the whole file by default.
 
 ### Issue tracker
@@ -18,30 +18,30 @@ do not read the whole file by default.
 
 ### Work history
 
-Shipped work is summarized in `.history/DD.MM.YYYY/README.md`. Use separated
+Shipped work is summarized in `.agentic-scaffold/.history/DD.MM.YYYY/README.md`. Use separated
 dated worklog files only; do not use issue comments as the project memory.
-After every successful coding session, follow `docs/agents/session-close.md`.
+After every successful coding session, follow `.agentic-scaffold/docs/agents/session-close.md`.
 
 ### Agent lifecycle hooks
 
-Pre/post lifecycle hooks live in `.agents/hooks/`. Implementation skills
+Pre/post lifecycle hooks live in `.agentic-scaffold/.agents/hooks/`. Implementation skills
 reference them automatically. Available hooks:
 
-- `.agents/hooks/pre-feature.md` — before implementing a feature
-- `.agents/hooks/post-feature.md` — after implementing a feature
-- `.agents/hooks/post-bugfix.md` — after fixing a bug
-- `.agents/hooks/post-session.md` — after a coding session (canonical
-  post-session workflow, replaces `docs/agents/session-close.md`)
-- `.agents/hooks/scripts/` — executable helpers for the hooks above
+- `.agentic-scaffold/.agents/hooks/pre-feature.md` — before implementing a feature
+- `.agentic-scaffold/.agents/hooks/post-feature.md` — after implementing a feature
+- `.agentic-scaffold/.agents/hooks/post-bugfix.md` — after fixing a bug
+- `.agentic-scaffold/.agents/hooks/post-session.md` — after a coding session (canonical
+  post-session workflow, replaces `.agentic-scaffold/docs/agents/session-close.md`)
+- `.agentic-scaffold/.agents/hooks/scripts/` — executable helpers for the hooks above
 
 ### Domain docs
 
-Use `BUSINESS_LOGIC.md`, `docs/`, and `docs/adr/` as tracked source material.
-See `docs/agents/domain.md`.
+Use `.agentic-scaffold/BUSINESS_LOGIC.md`, `.agentic-scaffold/docs/`, and `.agentic-scaffold/docs/adr/` as tracked source material.
+See `.agentic-scaffold/docs/agents/domain.md`.
 
 ### Coding principles
 
-Follow `docs/CODING_PRINCIPLES.md`: simple direct code, YAGNI, KISS, pragmatic
+Follow `.agentic-scaffold/docs/CODING_PRINCIPLES.md`: simple direct code, YAGNI, KISS, pragmatic
 DRY, existing conventions, explicit boundaries, fail-fast validation, and
 focused tests.
 
@@ -63,12 +63,12 @@ Memory and utility scripts use **{{scriptLanguage}}**.
 
 ### Agent memory
 
-Use repo automation from `scripts/`:
+Use repo automation from `.agentic-scaffold/scripts/`:
 
-- `scripts/memory_index.py` indexes project Markdown.
-- `scripts/memory_search.py` searches indexed Markdown.
-- `scripts/memory_bundle.py` writes a focused Markdown bundle for a task.
-- `scripts/sync-context.sh` syncs the generated historical `CONTEXT.md`.
+- `.agentic-scaffold/scripts/memory_index.py` indexes project Markdown.
+- `.agentic-scaffold/scripts/memory_search.py` searches indexed Markdown.
+- `.agentic-scaffold/scripts/memory_bundle.py` writes a focused Markdown bundle for a task.
+- `.agentic-scaffold/scripts/sync-context.sh` syncs the generated historical `CONTEXT.md`.
 
 Generated memory files live under `.memory/` and are gitignored.
 
@@ -83,5 +83,5 @@ Some files contain placeholder content that must be completed:
 {{/each}}
 
 To complete these, invoke the `fill-docs` skill:
-`.agents/skills/fill-docs/SKILL.md`
+`.agentic-scaffold/.agents/skills/fill-docs/SKILL.md`
 {{/if}}

package/templates/root/BUSINESS_LOGIC.md.hbs

@@ -30,6 +30,6 @@ Every future implementation plan must cite:
 
 - the relevant `BUSINESS_LOGIC.md` section;
 - any relevant ADR;
-- any relevant `docs/` file;
-- the issue and matching `.scratchpad/` detail file when the work is
+- any relevant `.agentic-scaffold/docs/` file;
+- the issue and matching `.agentic-scaffold/.scratchpad/` detail file when the work is
   issue-backed.

package/templates/root/CLAUDE.md.hbs

@@ -4,12 +4,12 @@
 
 ### Project brain
 
-Read `BUSINESS_LOGIC.md` first for product fundamentals, core domain concepts,
+Read `.agentic-scaffold/BUSINESS_LOGIC.md` first for product fundamentals, core domain concepts,
 non-negotiable rules, and decision references. Future task plans must cite the
-relevant `BUSINESS_LOGIC.md` section before implementation.
+relevant `.agentic-scaffold/BUSINESS_LOGIC.md` section before implementation.
 
 `CONTEXT.md` remains a generated historical mirror from the Obsidian vault. Use
-`docs/context/INDEX.md` to locate narrow sections when old context is needed;
+`.agentic-scaffold/docs/context/INDEX.md` to locate narrow sections when old context is needed;
 do not read the whole file by default.
 
 ### Issue tracker
@@ -18,41 +18,41 @@ do not read the whole file by default.
 
 ### Work history
 
-Shipped work is summarized in `.history/DD.MM.YYYY/README.md`. Use separated
+Shipped work is summarized in `.agentic-scaffold/.history/DD.MM.YYYY/README.md`. Use separated
 dated worklog files only; do not use issue comments as the project memory.
-After every successful coding session, follow `docs/agents/session-close.md`.
+After every successful coding session, follow `.agentic-scaffold/docs/agents/session-close.md`.
 
 ### Agent lifecycle hooks
 
-Pre/post lifecycle hooks live in `.agents/hooks/`. Implementation skills
+Pre/post lifecycle hooks live in `.agentic-scaffold/.agents/hooks/`. Implementation skills
 reference them automatically. Available hooks:
 
-- `.agents/hooks/pre-feature.md` — before implementing a feature
-- `.agents/hooks/post-feature.md` — after implementing a feature
-- `.agents/hooks/post-bugfix.md` — after fixing a bug
-- `.agents/hooks/post-session.md` — after a coding session (canonical
-  post-session workflow, replaces `docs/agents/session-close.md`)
-- `.agents/hooks/scripts/` — executable helpers for the hooks above
+- `.agentic-scaffold/.agents/hooks/pre-feature.md` — before implementing a feature
+- `.agentic-scaffold/.agents/hooks/post-feature.md` — after implementing a feature
+- `.agentic-scaffold/.agents/hooks/post-bugfix.md` — after fixing a bug
+- `.agentic-scaffold/.agents/hooks/post-session.md` — after a coding session (canonical
+  post-session workflow, replaces `.agentic-scaffold/docs/agents/session-close.md`)
+- `.agentic-scaffold/.agents/hooks/scripts/` — executable helpers for the hooks above
 
 ### Domain docs
 
-Use `BUSINESS_LOGIC.md`, `docs/`, and `docs/adr/` as tracked source material.
-See `docs/agents/domain.md`.
+Use `.agentic-scaffold/BUSINESS_LOGIC.md`, `.agentic-scaffold/docs/`, and `.agentic-scaffold/docs/adr/` as tracked source material.
+See `.agentic-scaffold/docs/agents/domain.md`.
 
 ### Coding principles
 
-Follow `docs/CODING_PRINCIPLES.md`: simple direct code, YAGNI, KISS, pragmatic
+Follow `.agentic-scaffold/docs/CODING_PRINCIPLES.md`: simple direct code, YAGNI, KISS, pragmatic
 DRY, existing conventions, explicit boundaries, fail-fast validation, and
 focused tests.
 
 ### Agent memory
 
-Use repo automation from `scripts/`:
+Use repo automation from `.agentic-scaffold/scripts/`:
 
-- `scripts/memory_index.py` indexes project Markdown.
-- `scripts/memory_search.py` searches indexed Markdown.
-- `scripts/memory_bundle.py` writes a focused Markdown bundle for a task.
-- `scripts/sync-context.sh` syncs the generated historical `CONTEXT.md`.
+- `.agentic-scaffold/scripts/memory_index.py` indexes project Markdown.
+- `.agentic-scaffold/scripts/memory_search.py` searches indexed Markdown.
+- `.agentic-scaffold/scripts/memory_bundle.py` writes a focused Markdown bundle for a task.
+- `.agentic-scaffold/scripts/sync-context.sh` syncs the generated historical `CONTEXT.md`.
 
 Generated memory files live under `.memory/` and are gitignored.
 
@@ -67,5 +67,5 @@ Some files contain placeholder content that must be completed:
 {{/each}}
 
 To complete these, invoke the `fill-docs` skill:
-`.agents/skills/fill-docs/SKILL.md`
+`.agentic-scaffold/.agents/skills/fill-docs/SKILL.md`
 {{/if}}

package/templates/scripts/memory_common.py.hbs

@@ -11,17 +11,17 @@ import sqlite3
 from pathlib import Path
 
 
-ROOT = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[2]
 DB_PATH = ROOT / ".memory" / "agent-memory.sqlite3"
 VECTOR_DIMS = 64
 
 INCLUDE_PATTERNS = (
-    "BUSINESS_LOGIC.md",
+    ".agentic-scaffold/BUSINESS_LOGIC.md",
     "AGENTS.md",
     "CLAUDE.md",
-    "docs/**/*.md",
-    ".scratchpad/**/*.md",
-    ".history/**/*.md",
+    ".agentic-scaffold/docs/**/*.md",
+    ".agentic-scaffold/.scratchpad/**/*.md",
+    ".agentic-scaffold/.history/**/*.md",
 )
 
 

package/templates/skills/bugfix/SKILL.md

@@ -9,5 +9,5 @@ Diagnose and fix a described bug.
 3. Identify the smallest root-cause fix.
 4. Add or update a regression test when practical.
 5. Run focused verification.
-6. If `.agents/hooks/post-bugfix.md` exists, read and follow it.
-   Otherwise record shipped work in `.history/DD.MM.YYYY/README.md`.
+6. If `.agentic-scaffold/.agents/hooks/post-bugfix.md` exists, read and follow it.
+   Otherwise record shipped work in `.agentic-scaffold/.history/DD.MM.YYYY/README.md`.

package/templates/skills/create-hook/SKILL.md

@@ -8,7 +8,7 @@ description: >
 
 # Create Hook
 
-Add a new agent lifecycle hook to `.agents/hooks/`. Hooks are markdown files
+Add a new agent lifecycle hook to `.agentic-scaffold/.agents/hooks/`. Hooks are markdown files
 that describe what an AI agent should do at a specific point in the workflow
 (pre-feature, post-bugfix, etc.).
 
@@ -28,7 +28,7 @@ already chains to `post-feature.md` and `post-bugfix.md`.
 
 ### 2. Name and create the hook file
 
-Name the file `<prefix>-<name>.md` and create it at `.agents/hooks/`. Use
+Name the file `<prefix>-<name>.md` and create it at `.agentic-scaffold/.agents/hooks/`. Use
 this anatomy:
 
 ```markdown
@@ -40,7 +40,7 @@ Fires <when this hook runs, e.g. "after every database migration">.
 
 1. First step the agent should take.
 2. Second step.
-3. Run `.agents/hooks/scripts/<name>.sh` if it exists.
+3. Run `.agentic-scaffold/.agents/hooks/scripts/<name>.sh` if it exists.
 
 ## When to skip
 
@@ -49,7 +49,7 @@ Conditions under which the agent should silently skip this hook.
 
 ### 3. Create the optional executable script
 
-If the hook needs automation, create `.agents/hooks/scripts/<name>.sh`:
+If the hook needs automation, create `.agentic-scaffold/.agents/hooks/scripts/<name>.sh`:
 
 ```bash
 #!/usr/bin/env bash
@@ -66,16 +66,16 @@ Add a conditional reference in every skill where the hook should fire.
 Use the existing pattern:
 
 ```markdown
-4. If `.agents/hooks/<hook-name>.md` exists, read and follow it.
+4. If `.agentic-scaffold/.agents/hooks/<hook-name>.md` exists, read and follow it.
 ```
 
 Skills commonly wired to hooks:
 
 | Skill | Hook point | File |
 |-------|-----------|------|
-| `implement` | pre + post | `.agents/skills/implement/SKILL.md` |
-| `bugfix` | post | `.agents/skills/bugfix/SKILL.md` |
-| `tdd` | pre + post | `.agents/skills/tdd/SKILL.md` |
+| `implement` | pre + post | `.agentic-scaffold/.agents/skills/implement/SKILL.md` |
+| `bugfix` | post | `.agentic-scaffold/.agents/skills/bugfix/SKILL.md` |
+| `tdd` | pre + post | `.agentic-scaffold/.agents/skills/tdd/SKILL.md` |
 
 ### 5. Wire into the session close chain
 

package/templates/skills/diagnose/SKILL.md

@@ -26,7 +26,7 @@ Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give
 7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
 8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
 9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `.agentic-scaffold/scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
 
 Build the right feedback loop, and the bug is 90% fixed.
 

package/templates/skills/fill-docs/SKILL.md

@@ -13,17 +13,17 @@ Search for these markers across the project:
 | Marker | File |
 |--------|------|
 | `<!-- Replace with... -->` | BUSINESS_LOGIC.md |
-| `<!-- Define your domain terms... -->` | docs/context/glossary.md |
-| `(populate as you...)` | docs/context/INDEX.md |
-| `Placeholder for...` | docs/product/README.md, docs/engineering/README.md |
+| `<!-- Define your domain terms... -->` | .agentic-scaffold/docs/context/glossary.md |
+| `(populate as you...)` | .agentic-scaffold/docs/context/INDEX.md |
+| `Placeholder for...` | .agentic-scaffold/docs/product/README.md, .agentic-scaffold/docs/engineering/README.md |
 
 ### 2. Prioritize
 
-1. **BUSINESS_LOGIC.md** — the project brain, read first by all agents
-2. **docs/context/glossary.md** — ubiquitous language that agents use
-3. **docs/product/README.md** — product spec extensions
-4. **docs/engineering/README.md** — implementation conventions
-5. **docs/context/INDEX.md** — navigation for historical context
+1. **.agentic-scaffold/BUSINESS_LOGIC.md** — the project brain, read first by all agents
+2. **.agentic-scaffold/docs/context/glossary.md** — ubiquitous language that agents use
+3. **.agentic-scaffold/docs/product/README.md** — product spec extensions
+4. **.agentic-scaffold/docs/engineering/README.md** — implementation conventions
+5. **.agentic-scaffold/docs/context/INDEX.md** — navigation for historical context
 
 ### 3. Interview and fill
 

package/templates/skills/implement/SKILL.md

@@ -1,17 +1,17 @@
 # Implement
 
-Use a short Linear issue plus a `.scratchpad/` detailed plan, then implement
+Use a short Linear issue plus a `.agentic-scaffold/.scratchpad/` detailed plan, then implement
 when not in Plan Mode.
 
 ## Steps
 
 1. Read `BUSINESS_LOGIC.md` and relevant ADRs.
-2. If `.agents/hooks/pre-feature.md` exists, read and follow it.
-3. Read the Linear issue and matching `.scratchpad/` detail file.
+2. If `.agentic-scaffold/.agents/hooks/pre-feature.md` exists, read and follow it.
+3. Read the Linear issue and matching `.agentic-scaffold/.scratchpad/` detail file.
 4. If no scratchpad detail exists, create one before coding.
 5. Implement the smallest complete slice that satisfies the plan.
 6. Run focused verification.
-7. If `.agents/hooks/post-feature.md` exists, read and follow it.
-   Otherwise record shipped work in `.history/DD.MM.YYYY/README.md`.
+7. If `.agentic-scaffold/.agents/hooks/post-feature.md` exists, read and follow it.
+   Otherwise record shipped work in `.agentic-scaffold/.history/DD.MM.YYYY/README.md`.
 
-Keep Linear descriptions short. Keep detailed reasoning in `.scratchpad/`.
+Keep Linear descriptions short. Keep detailed reasoning in `.agentic-scaffold/.scratchpad/`.

package/templates/skills/issue/SKILL.md

@@ -1,12 +1,12 @@
 # Issue
 
-Create a Linear issue and matching `.scratchpad/` detail file.
+Create a Linear issue and matching `.agentic-scaffold/.scratchpad/` detail file.
 
 ## Steps
 
 1. Read `BUSINESS_LOGIC.md`.
 2. Create a short Linear issue title and description.
-3. Create `.scratchpad/<feature-slug>/<issue-slug>.md` with context, scope,
+3. Create `.agentic-scaffold/.scratchpad/<feature-slug>/<issue-slug>.md` with context, scope,
    acceptance criteria, source references, and open questions.
 4. Link the Linear issue in the scratchpad file.
 5. Keep implementation details out of Linear unless they are essential.

package/templates/skills/monthly/SKILL.md

@@ -5,7 +5,7 @@ Create a monthly project summary.
 ## Steps
 
 1. Read `BUSINESS_LOGIC.md`.
-2. Read `.history/DD.MM.YYYY/README.md` files from the target month.
+2. Read `.agentic-scaffold/.history/DD.MM.YYYY/README.md` files from the target month.
 3. Review ADR changes from the month.
 4. Compare shipped work against roadmap and scratchpad plans.
 5. Summarize outcomes, decisions, risks, and next-month focus.

package/templates/skills/next/SKILL.md

@@ -0,0 +1,28 @@
+# Next
+
+Scan work history to determine the next development task. If no clear next step emerges, enter planning mode and interview the user.
+
+## Steps
+
+1. **Scan work history**
+   - Read `BUSINESS_LOGIC.md` for project goals and roadmap.
+   - Read `CONTEXT.md` (via `.agentic-scaffold/docs/context/INDEX.md`) for active context.
+   - Check `.agentic-scaffold/.scratchpad/` for active or ready work items.
+   - Read the latest entries in `.agentic-scaffold/.history/` (most recent day directories).
+   - Run `git log --oneline -20` to review recent commits.
+   - Check open issues or PRs if an issue tracker is configured.
+
+2. **Identify next work**
+   - Look for items marked as "next", "ready", or "todo" in scratchpad files.
+   - Check for blocked items whose blocker may have been resolved.
+   - Review recent git history for incomplete or interrupted work.
+   - Cross-reference against the roadmap for unstarted priorities.
+
+3. **Decide action**
+   - If a clear next task is found: present it to the user with a summary of why.
+   - If multiple candidates: rank them by priority and ask the user to pick.
+   - If nothing found: enter **planning mode** — ask the user what they want to work on next, then use `/to-issues` or `/to-prd` to formalize.
+
+4. **Execute or plan**
+   - If user confirms the next task, proceed with implementation.
+   - If user chooses planning, guide discovery of what to build next.

package/templates/skills/status/SKILL.md

@@ -6,6 +6,6 @@ Compare current work against the roadmap.
 
 1. Read `BUSINESS_LOGIC.md`.
 2. Read roadmap/backlog references in `CONTEXT.md` only through
-   `docs/context/INDEX.md`.
-3. Read `.scratchpad/` active plans and recent `.history/` entries.
+   `.agentic-scaffold/docs/context/INDEX.md`.
+3. Read `.agentic-scaffold/.scratchpad/` active plans and recent `.agentic-scaffold/.history/` entries.
 4. Report what is done, in progress, blocked, and next.

package/templates/skills/summary/SKILL.md

@@ -6,7 +6,7 @@ Create an all-time project summary.
 
 1. Read `BUSINESS_LOGIC.md`.
 2. Read `docs/adr/README.md` and accepted ADRs relevant to the summary.
-3. Read `.history/**/*.md`.
-4. Use `scripts/memory_search.py` for gaps.
+3. Read `.agentic-scaffold/.history/**/*.md`.
+4. Use `.agentic-scaffold/scripts/memory_search.py` for gaps.
 5. Summarize product direction, architecture, shipped work, open risks, and next
    likely work.

package/templates/skills/today/SKILL.md

@@ -1,14 +1,14 @@
 # Today
 
-Create today's plan from the roadmap, `.scratchpad/`, `.history/`, and vector
+Create today's plan from the roadmap, `.agentic-scaffold/.scratchpad/`, `.agentic-scaffold/.history/`, and vector
 memory.
 
 ## Steps
 
 1. Read `BUSINESS_LOGIC.md` first.
-2. Search `.scratchpad/` for active or ready work.
-3. Read the latest `.history/DD.MM.YYYY/README.md` files.
-4. Run `scripts/memory_search.py` for the user's stated focus if needed.
+2. Search `.agentic-scaffold/.scratchpad/` for active or ready work.
+3. Read the latest `.agentic-scaffold/.history/DD.MM.YYYY/README.md` files.
+4. Run `.agentic-scaffold/scripts/memory_search.py` for the user's stated focus if needed.
 5. Produce a short plan for today with references to source files.
 
 Do not create issues unless the user asks.

package/templates/skills/weekly/SKILL.md

@@ -5,6 +5,6 @@ Create a weekly project summary.
 ## Steps
 
 1. Read `BUSINESS_LOGIC.md`.
-2. Read `.history/DD.MM.YYYY/README.md` files from the target week.
-3. Check `.scratchpad/` for work that moved or remains blocked.
+2. Read `.agentic-scaffold/.history/DD.MM.YYYY/README.md` files from the target week.
+3. Check `.agentic-scaffold/.scratchpad/` for work that moved or remains blocked.
 4. Summarize shipped work, decisions, risks, and suggested next week focus.