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 |