Initialize a Project From Requirements

Purpose

Turn an early project idea into verifiable, file-based outputs:

• •Stage A (Requirements): four requirement documents under init/_work/stage-a-docs/
• •Stage B (Blueprint): a machine-readable init/_work/project-blueprint.json
• •Stage C (Scaffold + Skills): a minimal scaffold + skill pack manifest update + wrapper sync via node .ai/scripts/sync-skills.mjs

The initialize-project-from-requirements skill is designed to be bootstrap-only. After initialization, you may remove the init/ kit.

When to use

Use the initialize-project-from-requirements skill when:

• •The repo still contains an init/ directory (bootstrap kit present).
• •The user needs a clear, reviewable project description before implementation starts.
• •You want deterministic initialization outputs (docs + blueprint + minimal scaffold + skills enabled).

Do NOT use the skill when:

• •The repo has already been initialized and init/_work/project-blueprint.json is stable.
• •The user is asking for implementation work unrelated to initialization.
• •You do not have permission to generate or modify repo files.

Inputs

• •Repo root path (or run from repo root).
• •Stage A docs root: init/_work/stage-a-docs/ (created from templates in templates/)
• •Stage B blueprint: init/_work/project-blueprint.json

Optional inputs:

• •Provider set for wrapper sync: both (default), or codex, claude, codex,claude.

Outputs

• •Entry docs (human entry surface + generated routing):
  • •init/START-HERE.md (intake doc; LLM-maintained blocks)
  • •init/INIT-BOARD.md (LLM-owned; pipeline updates only the MACHINE_SNAPSHOT block)
• •Stage A docs (created/updated by the authoring process):
  • •init/_work/stage-a-docs/requirements.md
  • •init/_work/stage-a-docs/non-functional-requirements.md
  • •init/_work/stage-a-docs/domain-glossary.md
  • •init/_work/stage-a-docs/risk-open-questions.md
• •Stage B blueprint:
  • •init/_work/project-blueprint.json
• •Stage C scaffold (directories only; no framework code):
  • •src/ or (apps/, packages/) depending on repo.layout
• •Skills enabled (SSOT):
  • •.ai/skills/_meta/sync-manifest.json updated (based on skills.packs)
• •Provider wrappers regenerated:
  • •via node .ai/scripts/sync-skills.mjs

Critical Process Rules (MUST follow)

Rule 0: Entry Docs

• •init/START-HERE.md is the single intake surface for progressive, user-friendly input capture and organization.
  • •Only edit inside the BEGIN LLM / END LLM blocks.
• •Language gate: entry docs are created only after init/_work/.init-state.json has language set (free-form string).
  • •Ask the user to choose a working language, then run:
    • •node init/_tools/init.mjs start --repo-root .
    • •node init/_tools/init.mjs set-language --language "<your language>" --repo-root .
• •init/INIT-BOARD.md is LLM-owned. The pipeline updates ONLY the machine snapshot block:
  • •<!-- INIT-BOARD:MACHINE_SNAPSHOT:START --> ... <!-- INIT-BOARD:MACHINE_SNAPSHOT:END -->
  • •Do NOT edit inside those markers.
• •The machine snapshot is refreshed implicitly by every init pipeline command; use update-board --apply as the manual fallback.

Rule 1: State Tracking

• •Before starting, check for existing init/_work/.init-state.json
• •If found, resume from recorded state (ask user to confirm)
• •If not found, run node init/_tools/init.mjs start to create initial state
• •Validation fields (validated) are automatically updated by check-docs and validate commands
• •Document existence fields (docsWritten) are automatically updated when check-docs passes
• •Approval fields (userApproved) and stage transitions are updated via approve --stage <A|B|C> command
• •Interview progress fields (stage-a.mustAsk.*) are auto-marked complete when check-docs passes (Stage A validated).
• •LLM MUST NOT hand-edit init/_work/.init-state.json (except via the set-language command updating language).
  • •Use init/START-HERE.md LLM blocks for rolling notes and progress during the interview.
• •State file will be deleted when cleanup-init is run

Rule 2: Mandatory Checkpoints

• •EVERY stage transition requires explicit user approval
• •Use prompts from templates/stage-checkpoints.md
• •Do NOT proceed without user saying "continue" / "approved" / "yes"

Rule 3: Quality Self-Review

• •Before requesting user approval, complete the relevant checklist in templates/quality-checklist.md
• •If any checklist item is "No", iterate before proceeding

Steps

Stage A: interview -> requirement docs (verifiable)

1. •

   Initialize state: Run node init/_tools/init.mjs start to create init/_work/.init-state.json and seed init/_work/stage-a-docs/ + init/_work/project-blueprint.json templates.

2. •

   Set language (required before entry docs): Ask the user to choose a working language (free-form string), then run:

node init/_tools/init.mjs set-language --language "<your language>" --repo-root .
# Example:
# node init/_tools/init.mjs set-language --language "zh-CN" --repo-root .

This creates (copy-if-missing) init/START-HERE.md and init/INIT-BOARD.md.

1. •

   Domain terminology alignment (MUST ask, but completion is optional):

   • •Ask the user: "Before we collect requirements, would you like to align on domain terminology first?"
   • •Explain: "If your project has specific domain terms, abbreviations, or concepts that need shared understanding, we can document them in domain-glossary.md upfront."
   • •If user chooses YES:
     • •Guide user to list key domain terms
     • •Create/update init/_work/stage-a-docs/domain-glossary.md with provided terms
   • •If user chooses NO or LATER:
     • •Record the decision in init/_work/stage-a-docs/domain-glossary.md (for example: a short note Status: deferred or No special terms yet)
     • •Continue to next step; if domain terms emerge during interview, prompt to add them to glossary
   • •Asking the question is mandatory, but completing the glossary is optional - user may skip if terminology is straightforward
2. •

   Use templates/conversation-prompts.md to run a structured requirements interview.

3. •

   Confirm whether the heavy agent-builder workflow is needed; if not, plan to run Stage C with --skip-agent-builder --i-understand.

4. •

   (Optional) If you want progress visibility while interviewing, update init/_work/.init-state.json stage-a.mustAsk.* incrementally.

   • •Otherwise you can skip this: check-docs will auto-mark MUST-ask as complete when Stage A validates.
5. •

   Draft the four Stage A documents using templates under templates/.

6. •

   Self-review: Complete Stage A checklist in templates/quality-checklist.md.

7. •

   Validate Stage A docs:

node init/_tools/init.mjs check-docs --docs-root init/_work/stage-a-docs

Use strict mode when you need a hard gate (CI / regulated workflows):

node init/_tools/init.mjs check-docs --docs-root init/_work/stage-a-docs --strict

1. •CHECKPOINT A->B: Use prompt from templates/stage-checkpoints.md to request user approval.
2. •Wait for explicit user approval, then run:

node init/_tools/init.mjs approve --stage A

Stage B: requirements -> blueprint (machine-readable)

1. •Create init/_work/project-blueprint.json based on the Stage A docs.
2. •Validate the blueprint:

node init/_tools/init.mjs validate   --blueprint init/_work/project-blueprint.json

1. •Reconcile packs with capabilities (warn-only by default):

node init/_tools/init.mjs suggest-packs   --blueprint init/_work/project-blueprint.json   --repo-root .

If you want to add missing recommended packs into the blueprint (safe-add only):

node init/_tools/init.mjs suggest-packs   --blueprint init/_work/project-blueprint.json   --repo-root .   --write

1. •Self-review: Complete Stage B checklist in templates/quality-checklist.md.
2. •CHECKPOINT B->C: Use prompt from templates/stage-checkpoints.md to request user approval.
3. •Wait for explicit user approval, then run:

node init/_tools/init.mjs approve --stage B

Stage C: scaffold + enable packs + sync wrappers

1. •Dry-run the scaffold plan:

node init/_tools/init.mjs scaffold   --blueprint init/_work/project-blueprint.json   --repo-root .

1. •

   Handle config template coverage:

   • •Check if the selected repo.language + repo.packageManager combination has a template in templates/scaffold-configs/.
   • •If a template exists: The apply command will auto-generate base config files (e.g., package.json, tsconfig.json, go.mod).
   • •If no template exists: You MUST provide guidance to the user:
     • •Recommend essential config files based on the selected tech stack (e.g., for Python: requirements.txt or pyproject.toml, for Java: pom.xml or build.gradle).
     • •Suggest using framework-specific CLI tools (e.g., npm init, poetry init, dotnet new) to generate starter configs.
     • •Document the recommended config structure in init/_work/stage-a-docs/non-functional-requirements.md or create a brief setup guide.
     • •Do NOT skip the guidance step; users need clear next steps even when templates are unavailable.
2. •

   Apply scaffold + manifest update + wrapper sync:

node init/_tools/init.mjs apply   --blueprint init/_work/project-blueprint.json   --repo-root .   --providers codex,claude   --require-stage-a

--require-stage-a fails only on Stage A doc errors. For strict gating (treat warnings as errors), use --require-stage-a-strict.

If the user opts out of agent-builder, add:

--skip-agent-builder --i-understand

1. •Self-review: Complete Stage C checklist in templates/quality-checklist.md.
2. •CHECKPOINT C Complete: Use prompt from templates/stage-checkpoints.md to confirm completion. User will choose one of: "regen docs", "cleanup init", or "done".
3. •(Required) Review skill retention: Confirm which skills to keep vs prune, then mark the review complete:

node init/_tools/init.mjs review-skill-retention --repo-root .

1. •(Recommended) Re-generate root docs: If user replies "regen docs", (re)generate the root README.md + AGENTS.md from the blueprint:

node init/_tools/init.mjs update-root-docs --apply

1. •Approve Stage C: After handling user's choice (regen docs if selected), run:

node init/_tools/init.mjs approve --stage C

1. •(Optional) Remove the bootstrap kit if user chose "cleanup init" or explicitly requests later:

node init/_tools/init.mjs cleanup-init   --repo-root .   --apply   --i-understand --archive

Boundaries

• •Do not invent requirements. Resolve ambiguity with the user, or record the item as TBD in init/_work/stage-a-docs/risk-open-questions.md.
• •Do not add provider-specific assumptions into Stage A docs or the blueprint.
• •Do not edit .codex/skills/ or .claude/skills/ directly. Only update SSOT in .ai/skills/ and run node .ai/scripts/sync-skills.mjs --scope current --providers both --mode reset --yes. (The repo's SSOT rule applies.)
• •Scaffolding MUST NOT overwrite existing files; scaffolding should only create missing directories and small placeholder README.md files.
• •Exception: The root README.md will be replaced with a project-specific version generated from the blueprint. The replacement is intentional - the template README should be replaced with project documentation.
• •The root AGENTS.md will be updated from the blueprint (project type, tech stack, key directories) during Stage C apply.

Stage C: Skill Retention Review (required)

Before approving Stage C, you MUST review which skills to keep vs prune.

• •Start from templates/skill-retention-table.template.md and fill the Skill + Description columns in-chat (translate to the user's preferred language if needed). Do NOT save skill-retention-table.md as a file.
• •Ask the user to list skills to remove (name or path), then confirm before deleting.
• •Use node .ai/scripts/delete-skills.mjs --skills "<csv>" --dry-run, then re-run with --yes.

Root AGENTS.md update rules

Stage C apply (and update-root-docs) updates the root AGENTS.md from the blueprint. If manual edits are needed, follow these rules.

MUST Preserve (template repo structure)

Modification boundary: You are ONLY allowed to add/update: ## Project Type, ## Tech Stack, and entries in the ## Key Directories table. All other content MUST remain unchanged.

MUST Add/Update (project-specific info)

Note: Do NOT create a separate ## Capabilities section. Express capability info through Tech Stack rows (e.g., Frontend: React, Backend: Express, Database: PostgreSQL) and Key Directories entries (e.g., apps/frontend/, apps/backend/).

Update logic: If a section already exists (e.g., ## Project Type), update its content. If the section does not exist, insert the section in the appropriate location. Do NOT create duplicate sections.

Format Rules (LLM-friendly docs)

1. •Semantic density: One key fact per line; avoid filler text
2. •Structured data: Use tables for tech stack and directory mappings
3. •Token efficiency: Prefer abbreviations in tables (e.g., "TS" for TypeScript)
4. •Scannable: Keep sections short; use headers for navigation

Example: Updated AGENTS.md structure

# AI Assistant Instructions

## Project Type

{{project.name}} - {{project.description}}

## Tech Stack

| Category | Value |
|----------|-------|
| Language | {{repo.language}} |
| Package Manager | {{repo.packageManager}} |
| Layout | {{repo.layout}} |
| Frontend | {{capabilities.frontend.framework}} |
| Backend | {{capabilities.backend.framework}} |
| Database | {{capabilities.database.kind}} |

## Key Directories

| Directory | Purpose |
|-----------|---------|
| `src/` or `apps/` | Application code |
| `apps/frontend/` | Frontend application (if enabled) |
| `apps/backend/` | Backend services (if enabled) |
| `.ai/` | Skills, scripts, LLM governance |
| `dev-docs/` | Working documentation |

## Routing

[preserve original routing table]

## Global Rules

[preserve original global rules]

Included assets

Templates

• •templates/conversation-prompts.md - Question bank for Stage A interview
• •templates/START-HERE.template.md - Template for the intake doc init/START-HERE.md (LLM blocks)
• •templates/INIT-BOARD.template.md - Template for init/INIT-BOARD.md (LLM-owned; machine snapshot markers)
• •templates/requirements.template.md - Stage A requirements doc template
• •templates/non-functional-requirements.template.md - Stage A NFR doc template
• •templates/domain-glossary.template.md - Stage A glossary template
• •templates/risk-open-questions.template.md - Stage A risks template
• •templates/skill-retention-table.template.md - Post-init skill retention table (NEW)
• •templates/project-blueprint.example.json - Stage B blueprint example
• •templates/project-blueprint.schema.json - Stage B blueprint JSON schema
• •templates/init-state.schema.json - State tracking schema (NEW)
• •templates/init-state.example.json - Initial state template (NEW)
• •templates/quality-checklist.md - Semantic quality self-review (NEW)
• •templates/stage-checkpoints.md - User approval prompts (NEW)
• •templates/scaffold-configs/ - Base config file templates (NEW)

Scripts

• •scripts/init-pipeline.mjs - Main pipeline script (start, status, approve, validate, check-docs, scaffold, apply, cleanup)
• •scripts/scaffold-configs.mjs - Standalone config file generator (advanced usage, see note below)

Note on config generation:

The apply command generates config files by default. Use --skip-configs to disable config generation. The standalone scaffold-configs.mjs is useful when you only need to update configs (e.g., after editing the blueprint) without re-running the entire scaffold process.

Template coverage and fallback behavior:

• •Available templates are in templates/scaffold-configs/ (currently: typescript-pnpm/, go/, cpp-xmake/, react-native-typescript/).
• •When a template exists, config files are auto-generated during apply.
• •When no template exists, you MUST provide user guidance:
  • •Recommend essential config files based on the selected language/framework.
  • •Suggest framework-specific CLI commands (e.g., npm init, poetry init).
  • •Document recommendations in project docs or create a setup guide.
  • •Do NOT leave users without clear next steps.