Skill: initialize-project-from-requirements

The skill connects the end-to-end initialization flow:

requirements docs -> project blueprint -> scaffold/config generation -> skills sync

It records an auditable init state throughout the workflow so that each stage has an explicit validate + user approval checkpoint.

Goal: a robust, repeatable, rollback-friendly initialization workflow (not "fastest possible").

Human entry points (recommended)

•
LLM-first workflow:
1. •Ask the user to choose one output language for init artifacts
2. •Record the chosen language in the init state: init/_work/.init-state.json -> outputLanguage
3. •
  Then use:
  - •init/START-HERE.md (LLM-maintained; localized; user-friendly key input digest)
  - •init/INIT-BOARD.md (LLM-maintained; localized; concise progress board)
    
    •The init pipeline updates a machine snapshot block inside the file after each pipeline command
    
    •LLM MUST NOT edit the machine snapshot markers/section
•LLM gate (MUST): before any Stage A interview work, confirm the output language and keep all init outputs single-language

LLM driver protocol (required)

Output language (MUST happen first)

•Ask: "What language should I use for all init outputs (choose one)?"
•
Write the result to: init/_work/.init-state.json -> outputLanguage
- •Humans MUST NOT hand-edit the state file.
- •LLM MAY edit the state file only to set/update outputLanguage (do not change stages or validation flags).

After outputLanguage is set, run status once to refresh the board snapshot:

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs status --repo-root .

Entry docs maintenance (LLM)

•
init/START-HERE.md is the "one-screen" user entry:
- •Keep the file short and scannable.
- •
  Maintain:
  - •AI pending questions (next 3-5)
  - •Key inputs table with status (todo | confirmed | tbd) (status values are NOT translated)
  - •Current conclusions (<= 5 bullets)
- •At the start of each stage (A/B/C), roll the previous stage summary into a collapsed archive section at the bottom (LLM-written).
•
init/INIT-BOARD.md is the concise progress board:
- •Localize the board to outputLanguage.
- •Use the machine snapshot section (auto-updated) + init/_work/.init-state.json as the source of truth.

Inputs

Stage A (requirements docs, required)

Working location (default: init/_work/stage-a-docs/, legacy: init/stage-a-docs/):

•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, required)

Working location (default): init/_work/project-blueprint.json (legacy: init/project-blueprint.json)

After initialization completes, use cleanup-init --archive to archive:

•Stage A docs -> docs/project/overview/

•Blueprint -> docs/project/overview/project-blueprint.json

Optional: features

Feature flags live under blueprint.features.

No external payload directory is required. Feature templates live under:

•.ai/skills/features/<feature-id>/templates/ (some features source templates from nested skills; for database: .ai/skills/features/database/sync-code-schema-from-db/templates/)

Stage C apply materializes enabled features by copying templates into the repo (copy-if-missing by default) and then running the corresponding control scripts (Node under .ai/scripts/ and/or Python under .ai/skills/features/**/scripts/, depending on the feature).

Outputs (written to disk)

Working files (during initialization)

•
Entry docs:
- •init/START-HERE.md (human/LLM entry; LLM-maintained; localized; not SSOT)
- •init/INIT-BOARD.md (LLM-maintained; localized; contains an auto-updated machine snapshot section)
•Workspace operating rules: init/_work/AGENTS.md (copy-if-missing; applies to init/_work/**)
•Stage A docs: init/_work/stage-a-docs/* (legacy: init/stage-a-docs/*)
•Blueprint: init/_work/project-blueprint.json (legacy: init/project-blueprint.json)
•Init state file: init/_work/.init-state.json (legacy: init/.init-state.json)

Archived files (after `cleanup-init --archive`)

SSOT for archive paths - This section is the single source of truth for archive locations.

•Stage A docs: docs/project/overview/*
•Blueprint: docs/project/overview/project-blueprint.json

Stage C outputs

•
Directory scaffold (examples):
- •src/ or apps/ + packages/ (based on repo.layout)
- •docs/diagrams/ (if diagram capability is enabled)
- •ops/ (when packaging/deployment features are enabled)
•Config files generated by scripts/scaffold-configs.mjs (for example .gitignore, lint/test/format configs, depending on the blueprint)
•Root README.md may be generated from the blueprint when scripts/templates/README.template.md is present
•
Skills selection (SSOT):
- •.ai/skills/_meta/sync-manifest.json (flat schema: version/includePrefixes/includeSkills/excludeSkills)
- •If .ai/skills/_meta/ctl-skillpacks.mjs exists, pack toggles must be done via ctl-skillpacks
•
Provider wrappers generated/updated:
- •node .ai/scripts/sync-skills.mjs (supports --providers)

Optional feature outputs

Stage C materializes:

•Context Awareness (mandatory): docs/context/** + config/environments/**
•Database (SSOT-driven): db/** (when db.ssot=database) or prisma/** (when db.ssot=repo-prisma); skipped when db.ssot=none
•CI (provider-driven): .github/workflows/ci.yml (GitHub) or .gitlab-ci.yml (GitLab), ci/**; skipped when ci.provider=none
•UI (default-on): ui/** + docs/context/ui/** (set features.ui=false to skip)
•Environment (default-on): env/** + docs/project/env-ssot.json (set features.environment=false to skip)
•Packaging (default-on): ops/packaging/** + docs/packaging/registry.json (set features.packaging=false to skip)
•Deployment (default-on): ops/deploy/** (set features.deployment=false to skip)
•Observability (default-on): observability/** + docs/context/observability/** (set features.observability=false to skip)
•Release (default-on): release/** + .releaserc.json.template (set features.release=false to skip)

Mandatory workflow rules

•
Every stage transition requires validation + explicit user approval.
- •Validation is recorded in init/_work/.init-state.json (legacy: init/.init-state.json) by pipeline commands.
- •Stage advancement must use approve (humans MUST NOT hand-edit the state file to "skip" stages).
•Do not advance stages without explicit user approval.
•
Feature semantics:
- •Context awareness is mandatory (always enabled in Stage C).
- •Database is controlled by db.ssot (SSOT selection).
- •CI is controlled by ci.provider (provider selection).
- •Other features are default-on; blueprint.features.* is override-only (set false to skip).
- •blueprint.context.* is configuration only (mode/env list).
•The manifest schema is the flat schema (do not use older nested shapes like collections.current).
•Config generation has a single SSOT: scripts/scaffold-configs.mjs.
•Do not create dev-docs task bundles during initialization; use dev-docs after init completes.
•Keep init/START-HERE.md current as a one-screen "key inputs + pending questions" page (LLM-maintained). Refresh after pipeline commands and after new requirements input.

Standard workflow (run from repo root)

All command paths in the document assume you run from the repo root.

0) Initialize state

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs start --repo-root .

1) Stage A: validate requirements docs -> user approval

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs check-docs \
  --repo-root . \
  --strict

Required (unless explicitly bypassed): update the must-ask checklist (for the state board; see the full key list in init/_tools/skills/initialize-project-from-requirements/reference.md):

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs mark-must-ask \
  --repo-root . \
  --key onePurpose \
  --asked \
  --answered \
  --written-to init/_work/stage-a-docs/requirements.md

Bypass option (not recommended): approve Stage A without completing the checklist:

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs approve --stage A --repo-root . --skip-must-ask

After the user reviews Stage A docs and explicitly says "approved", run:

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs approve --stage A --repo-root .

2) Stage B: validate blueprint -> user approval

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs validate \
  --repo-root .

Optional: record that packs were reviewed (for the state board):

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs review-packs --repo-root .

After the user reviews the blueprint and explicitly approves, run:

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs approve --stage B --repo-root .

3) Stage C: write scaffold/configs/packs/features/wrappers -> user approval

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs apply \
  --repo-root . \
  --providers both

Safety: apply is a Stage C command and refuses to run in earlier stages by default. Override (not recommended):

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs apply --repo-root . --providers both --force --i-understand

Stage C apply may generate a project-specific root README.md from the blueprint via scripts/templates/README.template.md. If the file is generated, include README.md in the Stage C review.

Troubleshooting: if Stage C apply fails with EPERM when writing .codex/skills/ or .claude/skills/, re-run the same apply command in an elevated shell. Do not change the blueprint between attempts.

4) Stage C: skill retention and pruning (required before approval)

After Stage C apply, generate and fill the skill retention table:

•Ensure init/_work/skill-retention-table.template.md exists (legacy: init/skill-retention-table.template.md).
•Fill the table with current skills from .ai/skills/ (translate descriptions if needed).
•Ask the user which skills to keep/delete (record TBD if undecided).
•Preview deletions, then confirm and delete:

bash

node .ai/scripts/sync-skills.mjs --dry-run --delete-skills "<csv>"
node .ai/scripts/sync-skills.mjs --delete-skills "<csv>" --yes

Record that skill retention was reviewed (required before Stage C approval):

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs review-skill-retention --repo-root .

Optional: prune unused feature tooling (tests/scripts)

This template ships:

•Central feature-pack tests under .ai/tests/ (not per-skill tests/ folders)
•Feature controller scripts under .ai/skills/features/**/scripts/ (plus cross-cutting controllers under .ai/scripts/)

Initialization does not auto-delete these. If the user explicitly does not need the corresponding feature packs, you MAY remove the related paths (after confirmation), for example:

•DB mirror tooling: .ai/skills/features/database/sync-code-schema-from-db/scripts/ctl-db.mjs, .ai/skills/features/database/sync-code-schema-from-db/scripts/migrate.mjs
•CI tooling: .ai/skills/features/ci/scripts/ctl-ci.mjs
•Deployment tooling: .ai/skills/features/deployment/scripts/ctl-deploy.mjs, .ai/skills/features/deployment/scripts/rollback.mjs
•Packaging tooling: .ai/skills/features/packaging/scripts/ctl-pack.mjs
•Release tooling: .ai/skills/features/release/scripts/ctl-release.mjs
•Observability tooling: .ai/skills/features/observability/scripts/ctl-obs.mjs
•Feature-pack test suites: .ai/tests/suites/database/, .ai/tests/suites/environment/, .ai/tests/suites/ui/

After pruning, re-run wrapper sync:

bash

node .ai/scripts/sync-skills.mjs --scope current --providers both --mode reset --yes

5) Stage C: update root README.md and AGENTS.md (required before approval)

After Stage C apply and skill retention review, you must either update or explicitly skip the AGENTS.md update.

Explicitly ask the user:

Do you want to record the project type, tech stack, and key directories in the root AGENTS.md? (yes/no/skip)

If YES: run update-agents (dry-run, then apply):

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs update-agents --repo-root .
node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs update-agents --repo-root . --apply

If NO/SKIP: the user can skip the AGENTS.md update step during approval:

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs approve --stage C --repo-root . --skip-agents-update

Note: Stage C apply may already generate a project-specific root README.md from the blueprint.

Rationale: Without project-specific AGENTS.md content, LLMs will see only the generic template description, reducing context quality for future sessions.

6) Stage C approval (complete init)

After the user reviews the Stage C results and explicitly approves, run:

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs approve --stage C --repo-root .

7) Optional: remove the init kit

When the user confirms the bootstrap kit is no longer needed:

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs cleanup-init \
  --repo-root . \
  --apply \
  --i-understand

Safety: cleanup-init --apply refuses when the init state indicates an incomplete stage. Override (not recommended):

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs cleanup-init --repo-root . --apply --i-understand --force

State recovery

If a session is interrupted, recover the current state:

•Check for existing state file: init/_work/.init-state.json (legacy: init/.init-state.json)

•Use status to see the current stage and progress:

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs status --repo-root .

•Use advance to see the next checkpoint action:

bash

node init/_tools/skills/initialize-project-from-requirements/scripts/init-pipeline.mjs advance --repo-root .

Note: The state file is stored under init/_work/ and is intended as working data for initialization. Once the init kit is removed via cleanup-init, the state will be deleted as well.

Context Awareness feature notes

How the workflow is triggered

Context awareness is mandatory and always materialized during Stage C.

Configuration only:

•blueprint.context.mode: "contract" | "snapshot" (default: contract)

Key scripts

•
.ai/skills/features/context-awareness/scripts/ctl-context.mjs
- •init: initializes the docs/context/ scaffold (idempotent)
•
.ai/scripts/ctl-project-state.mjs
- •init: initializes .ai/project/state.json (idempotent)
- •set-context-mode <contract|snapshot>: sets the context mode
•
.ai/skills/_meta/ctl-skillpacks.mjs
- •enable-pack <packId> --no-sync: enables a pack (writes manifest)

For full details, see .ai/skills/features/context-awareness/.

Skill: initialize-project-from-requirements

Human entry points (recommended)

LLM driver protocol (required)

Output language (MUST happen first)

Entry docs maintenance (LLM)

Inputs

Stage A (requirements docs, required)

Stage B (blueprint, required)

Optional: features

Outputs (written to disk)

Working files (during initialization)

Archived files (after cleanup-init --archive)

Stage C outputs

Optional feature outputs

Mandatory workflow rules

Standard workflow (run from repo root)

0) Initialize state

1) Stage A: validate requirements docs -> user approval

2) Stage B: validate blueprint -> user approval

3) Stage C: write scaffold/configs/packs/features/wrappers -> user approval

4) Stage C: skill retention and pruning (required before approval)

Optional: prune unused feature tooling (tests/scripts)

5) Stage C: update root README.md and AGENTS.md (required before approval)

6) Stage C approval (complete init)

7) Optional: remove the init kit

State recovery

Context Awareness feature notes

How the workflow is triggered

Key scripts

Archived files (after `cleanup-init --archive`)