create-ai-pdlc-factory

create-ai-pdlc-factory

Phase 0 (init) implementation — the CLI that scaffolds a new project with the AI-PDLC harness root and walks the Builder into envisioning.

This is the implementation of the Phase 0 spec. It corresponds to the factory/ directory in the AI-PDLC Factory repository.

Status

v1.6.0 — full phase pipeline + executable validator chain + enforced push gate + live stack rules. See CHANGELOG.md for the release-by-release record (the authoritative status source; this section summarizes).

• Phase 0 scaffold: pnpm create ai-pdlc-factory <project-name> — .harness/ root, manifest, host entrypoints, git init, first-run UX

• Phases 0–9 ship as skills with schemas + lints (/lets-begin single entrypoint; phase skills are internal plumbing)

• ai-pdlc-harness lint <envision|stack|architecture|prd|chunk|build-session|review-report|retro> — 8 phase-artifact gates

• Pack architecture: monorepo workspaces, catalog stubs, ai-pdlc-harness apply-pack (fetch + apply + apply_report)

• ai-pdlc-harness validate — the four-layer validator chain (generic → stack → project → pr-shape), rule-module contract, scaffold arming

• Three implemented generic baseline rules in every scaffold (security-baseline/no-hardcoded-secret, code-hygiene/no-merge-conflict-markers, code-hygiene/no-skipped-test-without-reason)

• Per-edit hook: .harness/hooks/post-edit-validate.mjs + Claude Code wiring via .claude/settings.json (blockers block; warnings surface; "chain NOT run" is explicit, never silent)

• Pre-push pr-ready gate: ai-pdlc-harness gate pre-push|emit-pr-ready + versioned git hooks (core.hooksPath .harness/hooks/git) — plan branches require a fresh Phase 7 review flag bound to the pushed sha

• Claude Code host adapter (slash-command symlink with Windows copy fallback)

• tp-nuxt pack v1.1.0: all 8 stack rules implemented (live at apply time) + @validator-ignore inline suppression with mandatory reasons, counted per run

Not yet shipped (tracked in CHANGELOG "Not in this release" sections):

• Scaffold-promotion mechanics (ratchet writing rule bodies — project layer)
• Other host adapters (Cursor, Codex, Windsurf, JetBrains)
• Subscription auto-update / harness:upgrade / harness:audit
• npm publish of @bluevollc/pack-tp-nuxt (paused pending org admin transition)

Quick start

# from any directory
pnpm create ai-pdlc-factory my-project
cd my-project
# open in your AI-enabled editor and run /init

Development

pnpm install           # install deps
pnpm typecheck         # check types
pnpm test              # run integration tests
pnpm build             # emit dist/
pnpm cli <projectName> # run the CLI from source (via tsx)

To test the built CLI against a tmpdir:

pnpm build
(cd /tmp && node /home/tommy/projects/ai-pdlc-factory/factory/dist/cli.js my-test-project)

CLI flags

Flag	Type	Default	Behavior
<projectName>	positional, required	—	Directory name to create (kebab-case)
--host <id>	string	auto-detect	Comma-separated host ids: claude (v0.1 ships only Claude)
--name <display>	string	titlecased projectName	Human-readable project name written to manifest
--no-git	boolean	false	Skip git init + initial commit
--no-install	boolean	false	Skip dependency install (no-op until factory has runtime deps)
--quiet	boolean	false	Suppress progress output (still prints final next-move)
--help, -h	flag	—	Print help and exit

Exit codes (Phase 0 spec § exit codes)

Code	Meaning
0	Scaffold succeeded
1	Invalid arguments (missing name; non-kebab-case name)
2	Target directory not empty
5	Unknown host id supplied to --host
20	Unknown error (bug — please report)

Architecture

src/
├── cli.ts                 ← create-ai-pdlc-factory entrypoint (scaffold)
├── harness-cli.ts         ← ai-pdlc-harness entrypoint (lint / validate / apply-pack)
├── version.ts             ← single source of truth for factory version
├── paths.ts               ← locates templates/ from src or dist
├── commands/
│   ├── init.ts            ← orchestrator: scaffold + git + first-run
│   ├── lint.ts            ← 8 phase-artifact lint subcommands
│   ├── validate.ts        ← four-layer validator-chain CLI (runValidate)
│   └── apply-pack.ts      ← pack fetch + apply + apply_report stamping
├── validate/
│   ├── contract.ts        ← rule-module contract (scaffold-compatible, Zod)
│   ├── chain.ts           ← layer discovery + ordered execution + scaffold arming
│   └── glob.ts            ← dependency-free appliesTo matcher
├── lint/                  ← per-phase artifact lints (envision … retro)
├── intent/ stack/ architecture/ prd/ chunk/ build/ review/ reflect/
│                          ← Zod schemas per phase artifact
├── pack/
│   ├── source.ts          ← source_location URI parsing
│   ├── fetch.ts           ← builtin / workspace / file / npm fetch
│   └── apply.ts           ← template + skill + validator application
├── manifest/
│   ├── schema.ts          ← Zod schema for manifest.json
│   └── writer.ts          ← builds + writes the initial manifest
├── hosts/
│   ├── types.ts           ← HostAdapter interface
│   ├── registry.ts        ← detect + lookup
│   └── claude.ts          ← Claude Code adapter
├── scaffold/
│   └── files.ts           ← copy harness tree + write generic files + skill links
└── ux/
    └── first-run.ts       ← terminal output (next-move messaging)

templates/                 ← copied into every scaffolded project
├── harness/               ← .harness/ skeleton
│   ├── skills/generic/<phase>/SKILL.md   (lets-begin, init, envision, … reflect)
│   ├── skills/generic/stack-select/catalog/<pack>/pack.json (stubs)
│   ├── skills/{stack,project}/.gitkeep
│   ├── validators/generic/…              ← implemented baseline rules (trio per rule)
│   ├── validators/{stack,project}/.gitkeep
│   ├── vocabulary/.gitkeep
│   ├── glossary.md
│   └── subscription.json
├── AGENTS.md.tpl
├── README.md.tpl
└── gitignore.tpl

test/
├── unit/                  ← glob, rule contract, pack source URIs
└── integration/           ← scaffold, lints per phase, validate chain,
                             generic rules, pack fetch/apply, apply-pack CLI

Adding a new host adapter

1. Create src/hosts/<id>.ts implementing HostAdapter
2. Add it to HOST_REGISTRY in src/hosts/registry.ts
3. Add detection + entrypoint-writing tests to test/integration/scaffold.test.ts

The first-run UX (one host / multiple / none) already works for any future adapter — just plug into the registry.

Tech stack

Layer	Choice	Why
Runtime	Node ≥22	Matches Phase 0 spec's requirement
Language	TypeScript (ESM)	Type-safe; ESM is modern Node default
CLI framework	Citty	Modern, type-safe, ESM-native, UnJS-ecosystem-aligned
Interactive prompts	@clack/prompts	Best DX for the few prompts we use
Schema validation	Zod	Universal default for manifest + future AC verification
Tests	Vitest	Project-wide standard