Add manifest-driven scaffolding with create and scaffold-cleanup commands

.husky/pre-commit

@@ -1,13 +1,16 @@
-# Generate index.md files for ai/ and aidd-custom/ folders
+# Generate index.md files for ai/ and aidd-custom/ folders, and sync AGENTS.md / CLAUDE.md
 node bin/aidd.js --index "$(git rev-parse --show-toplevel)"
 
-# Stage any updated index.md files
-git add 'ai/**/index.md' 'aidd-custom/**/index.md' 2>/dev/null || true
+# Stage any updated index.md files and synced agent files
+git add 'ai/**/index.md' 'aidd-custom/**/index.md' AGENTS.md CLAUDE.md 2>/dev/null || true
 
 # Generate ToC for README.md
 npm run toc
 
 # Stage updated README.md if ToC was regenerated
 git add README.md 2>/dev/null || true
 
+# E2E tests are intentionally excluded here — they run real npm installs and
+# can take up to 180 s, which exceeds the release pipeline's hook timeout.
+# AI agents should run `npm run test:e2e` manually before committing.
 npm run test:unit

AGENTS.md

@@ -51,3 +51,15 @@ and read `aidd-custom/config.yml` to load configuration into context.
 ## Task Index
 
 fix bug => /aidd-fix
+
+## Testing
+
+The pre-commit hook runs unit tests only (`npm run test:unit`). E2E tests are excluded because they perform real installs and can take several minutes.
+
+**Before committing**, always run the full suite manually:
+
+```sh
+npm run test:e2e
+```
+
+This ensures integration behaviour is verified without blocking the commit hook or timing out the release pipeline.

CLAUDE.md

@@ -0,0 +1,65 @@
+# AI Agent Guidelines
+
+This project uses AI-assisted development with structured guidance in the `ai/` directory.
+
+## Directory Structure
+
+Agents should examine the `ai/*` directory listings to understand the available commands, rules, and workflows.
+
+## Index Files
+
+Each folder in the `ai/` directory contains an `index.md` file that describes the purpose and contents of that folder. Agents can read these index files to learn the function of files in each folder without needing to read every file.
+
+**Important:** The `ai/**/index.md` files are auto-generated from frontmatter. Do not create or edit these files manually—they will be overwritten by the pre-commit hook.
+
+## Progressive Discovery
+
+Agents should only consume the root index until they need subfolder contents. For example:
+- If the project is Python, there is no need to read JavaScript-specific folders
+- If working on backend logic, frontend UI folders can be skipped
+- Only drill into subfolders when the task requires that specific domain knowledge
+
+This approach minimizes context consumption and keeps agent responses focused.
+
+## Vision Document Requirement
+
+**Before creating or running any task, agents must first read the vision document (`vision.md`) in the project root.**
+
+The vision document serves as the source of truth for:
+- Project goals and objectives
+- Key constraints and non-negotiables
+- Architectural decisions and rationale
+- User experience principles
+- Success criteria
+
+## Conflict Resolution
+
+If any conflicts are detected between a requested task and the vision document, agents must:
+
+1. Stop and identify the specific conflict
+2. Explain how the task conflicts with the stated vision
+3. Ask the user to clarify how to resolve the conflict before proceeding
+
+Never proceed with a task that contradicts the vision without explicit user approval.
+
+## Custom Skills and Configuration
+
+Project-specific customization lives in `aidd-custom/`. Before starting work,
+read `aidd-custom/index.md` to discover available project-specific skills,
+and read `aidd-custom/config.yml` to load configuration into context.
+
+## Task Index
+
+fix bug => /aidd-fix
+
+## Testing
+
+The pre-commit hook runs unit tests only (`npm run test:unit`). E2E tests are excluded because they perform real installs and can take several minutes.
+
+**Before committing**, always run the full suite manually:
+
+```sh
+npm run test:e2e
+```
+
+This ensures integration behaviour is verified without blocking the commit hook or timing out the release pipeline.

README.md

@@ -37,6 +37,10 @@ Includes:
   - [Installation & Usage](#installation--usage)
   - [Command Options](#command-options)
   - [Examples](#examples)
+  - [`npx aidd create` — Scaffold a new project](#npx-aidd-create--scaffold-a-new-project)
+- [⚙️ Customizing aidd Framework for your Project](#-customizing-aidd-framework-for-your-project)
+  - [`aidd-custom/config.yml`](#aidd-customconfigyml)
+  - [`aidd-custom/AGENTS.md`](#aidd-customagentsmd)
 - [📁 AI System Structure](#-ai-system-structure)
   - [Key Components](#key-components)
 - [🎯 AI Integration](#-ai-integration)
@@ -418,6 +422,77 @@ npx aidd frontend-app
 npx aidd backend-api
 ```
 
+### `npx aidd create` — Scaffold a new project
+
+Use the `create` subcommand to scaffold a new project from a manifest-driven scaffold extension:
+
+```bash
+npx aidd create my-project                              # built-in next-shadcn scaffold
+npx aidd create scaffold-example my-project             # named scaffold bundled in aidd
+npx aidd create https://github.com/org/repo my-project  # remote GitHub repo (latest release)
+npx aidd create file:///path/to/scaffold my-project     # local scaffold directory
+```
+
+For full documentation on authoring your own scaffolds, see [docs/scaffold-authoring.md](./docs/scaffold-authoring.md).
+
+To avoid passing the URI on every invocation, save it to your user config with `set create-uri`. It is read automatically whenever you run `npx aidd create`:
+
+```bash
+npx aidd set create-uri https://github.com/org/scaffold
+npx aidd set create-uri file:///path/to/my-scaffold
+```
+
+The value is saved to `~/.aidd/config.yml`. You can also hand-edit it directly:
+
+```yaml
+# ~/.aidd/config.yml
+create-uri: https://github.com/your-org/my-scaffold
+```
+
+The lookup priority is:
+
+```
+CLI <type> arg  >  AIDD_CUSTOM_CREATE_URI env var  >  ~/.aidd/config.yml  >  default (next-shadcn)
+```
+
+## ⚙️ Customizing aidd Framework for your Project
+
+After installing the aidd system, create an `aidd-custom/` directory at your project root to extend or override the defaults without touching the built-in `ai/` files. Changes in `aidd-custom/` supersede the project root in case of any conflict.
+
+```
+your-project/
+├── ai/                        # built-in aidd framework files (don't edit)
+├── aidd-custom/               # your project-specific customizations
+│   ├── config.yml             # project-level aidd settings
+│   └── AGENTS.md              # project-specific agent instructions
+└── ...
+```
+
+### `aidd-custom/config.yml`
+
+Store project-level aidd settings as YAML (token-friendly for AI context injection):
+
+```yaml
+# aidd-custom/config.yml
+stack: next-shadcn
+team: my-org
+```
+
+### `aidd-custom/AGENTS.md`
+
+Project-specific instructions for AI agents. Write rules, constraints, and context that apply only to your project. AI agents are instructed to read `aidd-custom/AGENTS.md` after `AGENTS.md` — directives here override the defaults.
+
+```markdown
+# Project Agent Instructions
+
+## Stack
+We use Next.js 15 App Router with Tailwind CSS and shadcn/ui.
+
+## Conventions
+- All server actions live in `lib/actions/`
+- Use `createRoute` from `aidd/server` for API routes
+```
+
 ## 📁 AI System Structure
 
 After running the CLI, you'll have a complete `ai/` folder:

activity-log.md

@@ -1,3 +1,13 @@
+## February 18, 2026
+
+- 🚀 - `npx aidd create` - New `create [type|URI] <folder>` subcommand with manifest-driven scaffolding (run/prompt steps, --agent flag, remote code warning)
+- 🚀 - `npx aidd scaffold-cleanup` - New cleanup subcommand removes `.aidd/` working directory
+- 🔧 - Extension resolver - Supports named scaffolds, `file://`, and `https://`; remote scaffolds require HTTPS (`http://` URIs are rejected) with confirmation prompt for remote code
+- 🔧 - SCAFFOLD-MANIFEST.yml runner - Executes run/prompt steps sequentially; prompt steps use array spawn to prevent shell injection
+- 📦 - `scaffold-example` scaffold - Minimal E2E fixture: `npm init`, vitest test script, installs riteway/vitest/playwright/error-causes/@paralleldrive/cuid2
+- 📦 - `next-shadcn` scaffold stub - Default named scaffold with placeholder manifest for future Next.js + shadcn/ui implementation
+- 🧪 - 44 new tests - Unit tests for resolver, runner, cleanup; E2E tests covering full scaffold lifecycle
+
 ## October 20, 2025
 
 - 📱 - Help command clarity - AI workflow commands context

ai/commands/index.md

@@ -8,65 +8,43 @@ This index provides an overview of the contents in this directory.
 
 **File:** `aidd-fix.md`
 
-*No description available*
-
 ### Commit
 
 **File:** `commit.md`
 
-*No description available*
-
 ### discover
 
 **File:** `discover.md`
 
-*No description available*
-
 ### execute
 
 **File:** `execute.md`
 
-*No description available*
-
 ### help
 
 **File:** `help.md`
 
-*No description available*
-
 ### log
 
 **File:** `log.md`
 
-*No description available*
-
 ### plan
 
 **File:** `plan.md`
 
-*No description available*
-
 ### 🔬 Code Review
 
 **File:** `review.md`
 
-*No description available*
-
 ### run-test
 
 **File:** `run-test.md`
 
-*No description available*
-
 ### task
 
 **File:** `task.md`
 
-*No description available*
-
 ### user-test
 
 **File:** `user-test.md`
 
-*No description available*
-

ai/index.md

@@ -12,6 +12,10 @@ See [`commands/index.md`](./commands/index.md) for contents.
 
 See [`rules/index.md`](./rules/index.md) for contents.
 
+### 📁 scaffolds/
+
+See [`scaffolds/index.md`](./scaffolds/index.md) for contents.
+
 ### 📁 skills/
 
 See [`skills/index.md`](./skills/index.md) for contents.

ai/rules/index.md

@@ -60,8 +60,6 @@ When writing functional requirements for a user story, use this guide for functi
 
 **File:** `review-example.md`
 
-*No description available*
-
 ### 🔬 Code Review
 
 **File:** `review.mdc`
@@ -84,8 +82,6 @@ when the user asks you to complete a task, use this guide for systematic task/ep
 
 **File:** `tdd.mdc`
 
-*No description available*
-
 ### UI/UX Engineer
 
 **File:** `ui.mdc`

ai/rules/javascript/index.md

@@ -8,8 +8,6 @@ This index provides an overview of the contents in this directory.
 
 **File:** `error-causes.mdc`
 
-*No description available*
-
 ### JavaScript IO Guide
 
 **File:** `javascript-io-network-effects.mdc`
@@ -20,5 +18,3 @@ When you need to make network requests or invoke side-effects, use this guide fo
 
 **File:** `javascript.mdc`
 
-*No description available*
-

ai/rules/please.mdc

@@ -41,9 +41,9 @@ Commands {
   ✅ /task - use the task creator to plan and execute a task epic
   ⚙️ /execute - use the task creator to execute a task epic
   🔬 /review - conduct a thorough code review focusing on code quality, best practices, and adherence to project standards
+  🐛 /aidd-fix - fix a bug or implement review feedback following the full AIDD fix process
   🧪 /user-test - use user-testing.mdc to generate human and AI agent test scripts from user journeys
   🤖 /run-test - execute AI agent test script in real browser with screenshots
-  🐛 /aidd-fix - fix a bug or implement review feedback following the full AIDD fix process
 }
 
 Constraints {

ai/scaffolds/index.md

@@ -0,0 +1,14 @@
+# scaffolds
+
+This index provides an overview of the contents in this directory.
+
+## Subdirectories
+
+### 📁 next-shadcn/
+
+See [`next-shadcn/index.md`](./next-shadcn/index.md) for contents.
+
+### 📁 scaffold-example/
+
+See [`scaffold-example/index.md`](./scaffold-example/index.md) for contents.
+

ai/scaffolds/next-shadcn/README.md

@@ -0,0 +1,28 @@
+# next-shadcn
+
+The default AIDD scaffold for bootstrapping a Next.js project with shadcn/ui.
+
+## What this scaffold sets up
+
+- **Next.js** — React framework with App Router
+- **shadcn/ui** — accessible, composable component library
+- **Tailwind CSS** — utility-first CSS framework
+- **TypeScript** — static type checking
+- **Vitest** — fast unit test runner
+- **Playwright** — end-to-end browser testing
+
+## Usage
+
+```sh
+npx aidd create next-shadcn my-app
+```
+
+Or simply (next-shadcn is the default):
+
+```sh
+npx aidd create my-app
+```
+
+## Status
+
+This scaffold is a stub. Full implementation is planned for a future release.

ai/scaffolds/next-shadcn/SCAFFOLD-MANIFEST.yml

@@ -0,0 +1,2 @@
+steps:
+  - prompt: "This scaffold is a placeholder. Full next-shadcn scaffolding is coming soon. For now, please manually set up your Next.js project using: npx create-next-app@latest"

ai/scaffolds/next-shadcn/index.md

@@ -0,0 +1,10 @@
+# next-shadcn
+
+This index provides an overview of the contents in this directory.
+
+## Files
+
+### next-shadcn
+
+**File:** `README.md`
+