enhancement: scaffold starter vision.md / plan.md / activity-log.md / tasks/ at install

[griffinwork40]

Problem

The AIDD workflow expects four project-root artifacts to exist that npx aidd does not create:

File / dir	Required by	Citation
vision.md	"Before creating or running any task, agents must first read the vision document"	lib/agents-md.js:52, written into target's AGENTS.md
plan.md	/plan reads it; /task updates it	ai/commands/plan.md
activity-log.md	/log appends to it	ai/commands/log.md
tasks/	/task and /aidd-fix write epics to tasks/<name>-epic.md	ai/skills/aidd-fix/SKILL.md:44, ai/skills/aidd-task-creator/SKILL.md

Install creates none of these. After npx aidd ., the only post-install instruction is a console hint:

// lib/cli-core.js:189–197
logger.success("✅ Successfully cloned AI agent orchestration system!");
logger.info("Next steps:");
logger.gray("1. Create a vision.md document in your project root");
logger.gray("2. Navigate to your project directory");
logger.gray("3. Explore the ai/ folder for available commands and rules");
logger.gray("4. Start using AI Driven Development workflows");
logger.warning("💡 Tip: Create vision.md first, then try /help to see what you can do");

plan.md, activity-log.md, and tasks/ aren't mentioned at all. And the AGENTS.md text that ships into the target says agents should halt on missing vision content — which is undefined behavior when the file is missing entirely.

Why this matters

The AGENTS.md contract effectively binds the agent to read vision.md before any task. With no file present, the agent either:

• proceeds without a vision (silent contract violation), or
• hard-stops on a fresh install (terrible first-run experience).

Either path makes the workflow's first-touch UX worse than necessary, and it's avoidable with minimal scaffolding.

Suggested directions

1. Ship minimal starter templates as part of executeClone, each with skip-if-exists guards (same pattern aidd-custom/setup.js already uses):

   • vision.md — short template with the section headings AGENTS.md already enumerates (project goals, constraints, architectural decisions, UX principles, success criteria — lib/agents-md.js:55–61)
   • plan.md — empty epics list with the format /plan expects
   • activity-log.md — header only
   • tasks/.gitkeep — so the directory exists

2. Gate behind a flag like --templates (default off) or --no-templates (default on). Either is fine — the current default of "creates nothing" is the worst of both worlds because the workflow assumes they exist.

3. Update the "Next steps" output to mention all four artifacts and what each is for, even if templates aren't shipped.

Related

• Add CLAUDE.md generation and interactive vision.md command #88 (closed) proposed an interactive aidd vision command. This issue is narrower — just ship the templates so the workflow can run without an interactive step. The two proposals are complementary.

Expected

After npx aidd . (or npx aidd . --templates), a user can immediately run /task, /plan, or /log without first manually creating undocumented prerequisites.

Notes

Found during a third-party audit. Citations are against paralleldrive/aidd@57758344 (current main).