project-init

[IMPORTANT] Create complete task plan before shell checks, scans, generators, edits, or skill calls. [IMPORTANT] The config file is required, but only project.name is mandatory; select optional setup work from declared capabilities and repository evidence. [IMPORTANT] Run /scan-all only when selected built-in or generic scan targets apply; custom references default to manual ownership. Run /workflow-code-to-spec only for an existing spec corpus or accepted capability scope.

Quick Summary

Goal: Initialize or re-evaluate portable project context through one idempotent route, requiring a valid project identity while configuring only capabilities supported by the project and task.

Summary:

• Plan and assess the configured project, then repair the required config until non-empty project.name validates.
• Keep always-on context separate from exact task-specific reference selection; add optional capabilities only from evidence.
• Run scan, spec, surface, host, and graph work only when selected; preserve native spec formats or use strict defaults, then verify, review, and report outcomes and skips.
• Selected review setup delegates classifier/rule proposals and protected accepted merge to /project-config; initialization performs no review-tool acquisition.

Workflow:

1. Plan Tasks - Before setup, create task-tracking entries for required setup and review work; include conditional tasks only when their evidence and prerequisites apply.
2. Assess - Classify folder state and current context-file health.
3. Bootstrap - Require the configured config file with non-empty project.name; derive optional properties only from evidence.
4. Select Context Work - Ensure always-on lessons.md and docs-index-reference.md independently of task-specific referenceDocs; run only applicable selected/evidenced scans.
5. Spec Work - For selected spec work, preserve a valid native specArtifacts profile or use the strict TC/Section-8 default when absent. Select the spec workflow only when canonical specs exist or accepted capability scope is available.
6. Graph Refresh - Run /graph-code --mode=build in a background sub-agent only when graph tooling is available and the project/task needs graph coverage; otherwise record an evidence-backed skip.
7. Report - List completed actions, evidence-backed skips, blockers, and remaining manual steps.

Key Rules:

• MUST ATTENTION run this before ordinary work when required config/docs/root instruction files are missing.
• MUST ATTENTION preserve user-authored CLAUDE.md and AGENTS.md; use smart-merge/update paths, never blind overwrite.
• MUST ATTENTION keep reusable skill text project-neutral; local rules belong in project config/reference docs.
• MUST ATTENTION use configured portability paths from .claude/.ck.json when present.
• MUST ATTENTION before any shell check, scan, generator, or file edit, create a complete task plan covering assessment, setup routes, final skill calls, verification, report, and lessons.
• MUST ATTENTION treat only the config file and non-empty project.name as required; valid omitted capability sections do not make the config incomplete.
• MUST ATTENTION distinguish absent referenceDocs (portable baseline, possibly empty, plus evidenced capabilities) from an explicit array (authoritative, including []); always-on lessons.md and docs-index-reference.md are handled separately.
• MUST ATTENTION run /scan-all only for selected/evidenced built-in targets or custom docs explicitly marked scanTarget: "generic"; custom docs otherwise remain manual and are not freshness-tracked.
• MUST ATTENTION run /workflow-code-to-spec only when an existing canonical spec corpus or accepted project/capability scope supplies a real owner target; code/package names alone are not acceptance.
• MUST ATTENTION if both scan and spec work are selected, run them as siblings and wait for both outcomes; otherwise run only the applicable task.
• MUST ATTENTION preserve valid native specArtifacts; absence keeps strict TC/Section-8 defaults; an invalid declared profile blocks spec setup instead of falling back silently.
• MUST ATTENTION keep /changes-review --defer=whole-target then /why-review as final review gates after setup changes; report a no-change result when no artifacts were modified.
• MUST ATTENTION run /graph-code --mode=build as a background sub-agent only when graph tooling is available and graph work is relevant; do not make graph support a hidden prerequisite for non-code projects.
• MUST ATTENTION resolve Codex mirrors through the /ai-context-refresh completion handoff when Codex context is installed or selected; otherwise record the host-specific step as not applicable.
• MUST ATTENTION when the user asks for help, options, or "what does init decide", run Help Mode below and STOP — never start Phase -1.

Contents

• Quick Summary
• Help Mode (--help)
• Scope
• Phase -1: Required Task Plan
• Phase 0: Assess State
• Phase 1: Decide Route
• Phase 2: Execute Order
• Phase 2.5: Conditional Spec Workflow
• Phase 2.6: Final Review Skills
• Phase 3: Agent Rule When The Init Gate Has Not Run
• Phase 4: Verification
• Phase 5: Conditional Graph Refresh
• Output
• Closing Reminders

Help Mode (--help)

Trigger: $ARGUMENTS contains --help, -h, help, options, what does this set up, what will it change, or any other request to understand the setup surface rather than to run setup.

Help Mode is read-only and terminal. It creates no tasks, runs no scan, generates no file, and edits nothing. Answer, then STOP. If the user then asks to initialize, re-enter this skill at Phase -1.

1. What init decides (read this out, it is the part that is skill-owned)

Decision	Inputs it reads	Effect if you get it wrong
Route (greenfield / bootstrap / repair / re-evaluate)	session-init-helpers.cjs state checks in Phase 0	A repair route run on a greenfield tree overwrites nothing but reports nothing useful; the reverse regenerates context the project already owns
Required config identity	the configured project-config path, non-empty project.name	Every downstream skill blocks on invalid config
Optional capability sections	repository evidence, not the project name	An invented section makes skills demand a lane the project does not have
Always-on vs task-specific reference docs	lessons.md + docs-index-reference.md are always-on; referenceDocs[] is task-specific selection	Selecting a built-in doc with no owning scan target leaves a permanently stale file
Spec profile	specArtifacts (valid native profile) else strict TC/Section-8 defaults	An invalid declared profile BLOCKS spec setup; it never falls back silently
Host mirrors	/ai-context-refresh completion handoff	Hand-edited .agents/** is overwritten on the next sync

2. The option surface it configures

Init writes the project-config file, so the full option catalog is the same one /project-config --help renders. Run the generator directly:

node .claude/skills/project-config/scripts/project-config-help.cjs            # orientation + most-consumed options
node .claude/skills/project-config/scripts/project-config-help.cjs --sections # every option init can write
node .claude/skills/project-config/scripts/project-config-help.cjs --roots    # relocatable roots init resolves
node .claude/skills/project-config/scripts/project-config-help.cjs --docs     # reference docs init selects, and their owners
node .claude/skills/project-config/scripts/project-config-help.cjs --consumers # how much of the framework each option moves
node .claude/skills/project-config/scripts/project-config-help.cjs --current  # what THIS project already declares

3. Current state of this project (run before answering "what would init do here?")

node -e "const h=require('./.claude/hooks/lib/session-init-helpers.cjs'); console.log(JSON.stringify({hasProjectContent:h.hasProjectContent(), isGreenfield:h.isGreenfieldProject()}, null, 2))"
node -e "const s=require('./.claude/hooks/lib/session-init-helpers.cjs'); console.log(JSON.stringify(s.checkProjectConfig(), null, 2))"
node -e "const a=require('./.claude/hooks/lib/agent-files-state.cjs'); console.log(JSON.stringify(a.getAgentFileIssues(), null, 2))"

Map the result onto the Phase 1 route table and tell the user which route init would take and which steps it would skip, with the evidence for each skip.

Presentation rules:

• Show generator output verbatim; it is derived from live sources, so never retype an option list from memory.
• Name skipped steps explicitly. "Not applicable, because <evidence>" is an answer; silence is not.
• For framework-wide help beyond setup (skills, workflows, hooks, project architecture), suggest the user run /project-help, or read .claude/docs/README.md.

Scope

/project-init is the canonical coordinator for portable setup. It does not replace lower-level skills; it decides which one to run and when:

Concern	Primary route
Project config	/project-config; the configured file is required and its minimum valid content is non-empty project.name. Add optional capabilities only from evidence.
User/downstream experience	/experience-review after a runnable outcome exists; during setup, configure the matrix or record evidence-backed NOT-APPLICABLE/ENVIRONMENT-BLOCKED
Project reference docs	Ensure always-on lessons.md and docs-index-reference.md separately. Use /scan-all only for selected/evidenced applicable targets; use /docs-manager --mode=init, a built-in /scan --target=<key>, or the configured generic target for a selected stub/focused repair.
Root AI context	/ai-context-refresh
Codex mirror, AGENTS.md, .agents, .codex	Consume the /ai-context-refresh completion handoff when Codex context is present or requested; if required and unavailable, report the exact /sync-codex route.
Canonical specification and test-case artifacts	/workflow-code-to-spec only when canonical artifacts exist or an accepted product/capability scope identifies the owner target. Resolve specRoots.business.path when configured; a valid specArtifacts profile supplies the native format, while absence keeps strict TC/Section-8 defaults.
Knowledge graph	Background /graph-code --mode=build only when graph tooling is available and selected by code relationships or the active task.

Project-init test matrix — Defines config validity, optional capability selection, reference-doc semantics, spec-profile routing, and project-neutral setup behavior. MUST ATTENTION read references/use-cases-and-test-cases.md when creating plans, tests, or reviewing changes to this setup.

Phase -1: Required Task Plan

Before Phase 0 shell checks, create a full task-tracking plan. The plan MUST include many small, observable tasks and MUST NOT start execution until these rows exist.

Minimum required task rows:

1. Read project-init instructions and setup reference files.
2. Assess configured config path/status, always-on docs, task-selected references, applicable root instructions/host mirrors, and evidence for optional capabilities.
3. Run /project-config when the required config is missing, invalid, or stale; accept a valid config containing only project.name.
4. Verify or initialize always-on lessons.md and docs-index-reference.md independently of task-specific referenceDocs.
5. Select scan targets from the exact referenceDocs selection or repository evidence; call /scan-all only when at least one applicable target exists, otherwise record each evidence-backed skip.
6. Decide whether an existing spec corpus or accepted product/capability scope provides a real spec owner; call /workflow-code-to-spec only for that scope, otherwise record an evidence-backed deferral.
7. If both scan and spec work are selected, wait at a barrier until both finish or return an explicit blocker/deferral.
8. Run /ai-context-refresh when root instructions are missing or stale; otherwise record the verified state.
9. Resolve Codex mirrors through the completed /ai-context-refresh handoff only when Codex context is present or requested.
10. Configure or review experienceVerification only for evidenced observable surfaces; do not invent surface commands or baselines.
11. Call /changes-review --defer=whole-target after selected setup/scan/spec work.
12. Call /why-review after /changes-review --defer=whole-target.
13. Run focused verification for changed config, selected docs, and generated outputs; run broader harness gates only when the change plan calls for them.
14. Spawn Spawn background /graph-code --mode=build sub-agent only when graph tooling is available and graph work is relevant; otherwise record the evidence-backed skip.
15. Record the graph sub-agent outcome or skip reason.
16. Report the configured identity, changed optional properties, applicable scan/spec outcomes, always-on context, reviews, verification, graph outcome/skip, and remaining actions.
17. Analyze AI mistakes and reusable lessons.

Keep exactly one row in_progress. Mark each row completed immediately after its evidence is recorded.

Phase 0: Assess State

Use shell checks, not memory. Record evidence for every state claim:

node -e "const h=require('./.claude/hooks/lib/session-init-helpers.cjs'); console.log(JSON.stringify({hasProjectContent:h.hasProjectContent(), isGreenfield:h.isGreenfieldProject()}, null, 2))"
node -e "const s=require('./.claude/hooks/lib/session-init-helpers.cjs'); console.log(JSON.stringify(s.checkProjectConfig(), null, 2))"
node -e "const a=require('./.claude/hooks/lib/agent-files-state.cjs'); console.log(JSON.stringify(a.getAgentFileIssues(), null, 2))"

Also check:

• Config path: node -e "console.log(require('./.claude/hooks/lib/project-config-loader.cjs').getConfiguredProjectConfigPath())"
• Config status: only the file and non-empty project.name are required. A valid config with omitted optional properties is initialized, not a skeleton; repair any invalid declared section before ordinary work.
• Reference selection: absent referenceDocs lets the resolver choose its portable baseline (which can be empty) plus evidenced capabilities; an explicit array, including [], is authoritative for task-specific docs. Do not compare it with or restore a full reference catalog.
• Custom reference ownership: referenceDocs[].scanTarget is optional. Built-in docs keep their framework target; custom docs default to manual, while generic opts into one selected evidence-based scan using configured purpose and optional sections.
• Always-on inputs: check lessons.md and docs-index-reference.md under the configured project-reference root independently of referenceDocs.
• Experience path: inspect experienceVerification only when an observable project surface is evidenced or in scope; configuration never substitutes for live evidence.
• Docs index path: node -e "console.log(require('./.claude/hooks/lib/project-config-loader.cjs').getConfiguredDocsIndexPath())"
• Project-reference root: resolve it with getDocsRoot('projectReference'); inspect only the always-on docs and task-selected/evidenced references needed for this run.
• Placeholder/stale docs: use isPlaceholderFile() and getStaleReferenceDocs() for selected task-specific docs, not every file in the reference catalog.
• Spec inventory: inspect a configured or repository-evidenced canonical spec root only when a spec corpus or accepted capability scope is found. A missing default root alone does not select spec creation.

If specArtifacts is present, require it to validate before spec work. Preserve a valid native profile; absence keeps the strict TC/Section-8 default when a spec workflow is selected; a malformed declared profile blocks that work rather than silently falling back.

Phase 1: Decide Route

State	Action
Empty folder, no real project content	Do not deep-scan. Create a valid minimal config only when initialization was explicitly requested; derive project.name from repository metadata or the root directory. Do not invent capabilities, reference docs, or specs.
Greenfield project with manifests/code scaffold	Run /project-config when the required config is missing or invalid. Add only metadata and capabilities proven by the manifest/source. Manifests and package names alone do not define accepted product scope.
Existing project, config missing or invalid	Run /project-config first and stop ordinary setup until the required file validates. A minimal valid config with project.name is sufficient when no optional capability is evidenced.
Existing project, config valid but optional properties omitted	Treat it as initialized. Add only requested/evidenced capabilities; do not route back to /project-config solely to fill every optional section.
Custom workflow-route protocol requested (team or machine-only)	Team value → portability.workflowRouteProtocol in the configured project-config file; machine-only value → git-ignored .claude/.ck.local.json (a valid local value replaces the team value). Runtime-only: never regenerate tracked CLAUDE.md/AGENTS.md/Codex context to apply it.
Configured observable surface is in scope	Preserve existing testing practices. Configure only evidence-backed surface/tool facts, then defer live /experience-review until an entry point and inspection capability are available.
e2eTesting.execution is absent or partial for an evidenced E2E surface	Preserve known facts, then derive only the missing values from the linked surface config, E2E reference, runner configs, package/task scripts, compose/CI files, fixtures/seed scripts, and auth docs. Record file:line evidence; never invent commands, ports, accounts, selectors, or secrets.
Configured observable surface is relevant but cannot run or be inspected	Record ENVIRONMENT-BLOCKED with the missing capability and evidence. Do not substitute a screenshot, source review, or passing automated test for the missing exercise.
Always-on lessons.md or docs-index-reference.md missing/stale	Create/refresh these through their owner setup routes at the configured project-reference root; their lifecycle is independent of task-specific referenceDocs.
A selected/evidenced task-specific reference is missing, a placeholder, or stale	Run only its applicable built-in scan target or explicitly generic custom target, using /scan-all when multiple targets are selected. Manual custom docs remain owner-managed. Explicit referenceDocs: [] selects no task-specific doc scan.
referenceDocs absent	Use the resolver's portable baseline (possibly empty) and capability-aware selection from config/repository evidence; keep the property absent unless the project wants a fixed explicit selection.
referenceDocs explicitly lists a subset or []	Preserve it exactly as task-specific selection. Do not restore unselected catalog entries; continue ensuring always-on docs separately.
CLAUDE.md missing	Run /ai-context-refresh --mode init when the Claude host/root context is in use.
CLAUDE.md exists but is stale, markerless, or still carries legacy universal sections	The root holds project information only; universal rules reach every session by hook, so never copy framework rules or protocol text into it. Marker-managed and stale → /ai-context-refresh --mode update. Markerless/project-only → project-owned: keep it as is, or run /ai-context-refresh --mode update to smart-merge the generated project sections around its text. Legacy universal sections or sentinels → /ai-context-refresh --mode update --strip-legacy-universal (writes a backup first).
AGENTS.md, .agents, or .codex missing/incomplete and Codex is present/requested	Consume the /ai-context-refresh completion handoff; if unavailable, report the /sync-codex route.
Canonical specs exist, or accepted product/capability scope identifies a spec owner	Run /workflow-code-to-spec for the selected owner. Existing specs normally select audit, or update when an active requirement/change is in scope. If no owner/scope exists, defer spec authoring with evidence; code/package names alone are insufficient.
Existing native spec profile is valid	Preserve specArtifacts and route through its configured identifiers, sections, owners, and carriers. Do not translate it to TC identifiers.
specArtifacts is absent	When a spec workflow is selected, apply strict business-spec and Section-8 TC defaults. Do not create a profile just to avoid those defaults.
specArtifacts is declared but malformed/unsupported	Stop spec-related setup, retain the declared profile for diagnosis, and route to /project-config to repair it. Never drop the declaration and continue with TC defaults.
Graph tool and code relationship scope are available	Run /graph-code --mode=build in a background sub-agent after setup/review/verification; otherwise record an evidence-backed skip.
Everything present and valid	Report verified idempotent state. Do not schedule scans, spec creation, or graph work without a selected/evidenced capability.

Phase 2: Execute Order

Run required setup in order. Only scan/spec work selected from project evidence may run in parallel. After a material setup phase, re-check the configured project state.

1. Required config — run /project-config when the configured file is missing, invalid, or stale for an in-scope capability. A schema-valid config with only project.name is sufficient when no optional capability applies.

2. Always-on context — ensure lessons.md and docs-index-reference.md at the configured project-reference root through their owner setup routes. This is independent of referenceDocs.

3. Select reference scans — absent referenceDocs uses the portable resolver baseline (which may be empty) plus configured/repository-evidenced capabilities; an explicit array, including [], is authoritative for task-specific docs. Do not merge to a fixed floor, rename files, or generate an unselected reference. Use /scan-all only when one or more applicable targets are selected.

4. Select spec work — create a task for /workflow-code-to-spec only when a canonical spec corpus exists or accepted project/capability scope names the owner to document. If neither exists, record an evidence-backed deferral; code/package names alone do not establish acceptance. Preserve a valid native specArtifacts profile; absent profile means strict TC/Section-8 behavior; an invalid declared profile blocks the spec task.

5. Post-config selected work — when both scan and spec tasks apply, create them as sibling tasks and run them in parallel when the host supports it; otherwise finish both before crossing the barrier. When only one applies, run only that task. Every selected task must return completed, blocked, or evidence-deferred before final review.

6. Experience/E2E — configure or review the experienceVerification/e2eTesting matrix only for evidence-backed observable surfaces. Use /experience-review or E2E workflows when the surface can actually run and be inspected; missing prerequisites are ENVIRONMENT-BLOCKED, not PASS/N/A. Never create an expected baseline from current output.

7. Convention classes — run the detector only when stable contextGroups or convention injection is selected. Apply a write only when the configured preference or explicit request authorizes it; do not turn on injection merely because the detector found candidates. Verify a representative file with file-conventions.cjs --lookup when enabled.

8. Root instructions — run /ai-context-refresh --mode init|update when CLAUDE.md or equivalent root context is missing/stale, preserving user-authored content.

9. Codex mirror — consume the /ai-context-refresh completion handoff when Codex files/host are present or requested; otherwise record the Codex-only step as not applicable.

10. Enhance — use /prompt-enhance for newly created or materially updated project guidance when prompt quality warrants it.

11. Verification — validate config, selected references, root files, and mirrors that apply; run focused checks for changed behavior.

12. Graph refresh — after verification and reviews, run /graph-code --mode=build in a background sub-agent only when graph tooling is available and relevant; otherwise record the evidence-backed skip.

Phase 2.5: Conditional Spec Workflow

When existing canonical specs or accepted product/capability scope selects spec work:

• Resolve the configured business-spec root. Do not infer a new owner from a missing default directory.
• For existing specs, choose audit unless an active requirement/code change selects update.
• For accepted new capability scope, choose init-full for only the accepted scope; apply the workflow's large-scope decomposition rules to that set.
• Use the existing valid specArtifacts profile as the native section/ID/case format. If absent, apply strict business-spec and Section-8 TC defaults. If malformed/unsupported, stop spec setup and repair through /project-config; do not drop it or fall back silently.
• If no existing spec owner or accepted capability scope exists, do not call the spec workflow to manufacture one. Report the evidence and the route needed to establish scope.

Phase 2.6: Final Review Skills

After selected setup, scan, and spec work, create and execute these final tasks in order:

2. Call /changes-review --defer=whole-target - run after all selected setup, scan, and spec work so changed config/context/artifacts are reviewed from the current diff.
3. Call /why-review - run after /changes-review to validate rationale and avoid closing on unchallenged setup decisions.

If a listed task's skill cannot run because the environment lacks the required tool, stop and report the missing tool. If no files changed, still record that result rather than claiming a review of nonexistent changes.

Phase 3: Agent Rule When The Init Gate Has Not Run

For Codex or any environment where the init-prompt gate has not run:

• If the configured project-config file, always-on docs, applicable root instruction files, or a task-required reference doc is missing or stale, invoke /project-init before ordinary task work. Resolve config/index paths through the configured path helpers and the reference root through getDocsRoot('projectReference').
• If /project-init cannot run because required tools are absent, report the missing tool and the exact lower-level route that remains.
• Do not proceed with project-specific coding from guessed context.

Phase 4: Verification

Verify the required project identity, every declared optional property, and each changed or selected output before declaring setup complete. A valid config containing only non-empty project.name passes when no optional capability applies.

node -e "const{spawnSync}=require('child_process');const path=require('path');const configPath=require('./.claude/hooks/lib/project-config-loader.cjs').getConfiguredProjectConfigPath();const result=spawnSync(process.execPath,[path.resolve('.claude/hooks/lib/project-config-schema.cjs'),'--validate',configPath],{stdio:'inherit'});if(result.error){console.error(result.error.message);process.exitCode=1}else process.exitCode=result.status??1"
node -e "const l=require('./.claude/hooks/lib/project-config-loader.cjs');console.log(JSON.stringify({docsIndex:l.getConfiguredDocsIndexPath(),referenceRoot:l.getDocsRoot('projectReference')},null,2))"
node .claude/skills/skill-creator/scripts/validate-skills.cjs --path .claude/skills/project-init

For setup behavior changes, run focused tests that cover the changed contract. For example, use node .claude/hooks/tests/run-all-tests.cjs --filter=init-reference-docs when changing reference selection, and --filter=docroot-relocation or --filter=reference-doc-freshness when those behaviors changed. Do not run the full hook suite merely because project initialization completed; include broader harness checks when the framework-change plan requires them.

For selected spec work, confirm:

• Confirm an existing canonical owner or accepted capability scope selected the work; otherwise do not create specs or test cases and record the evidence-backed deferral.
• Confirm the configured business-spec root resolves through getSpecDocsPath() only when selected spec work needs it; the default is docs/specs (a specRoots.business.path entry in docs/project-config.json overrides it).
• Preserve and validate a declared native specArtifacts profile. When absent, use strict TC/Section-8 defaults for the selected spec work; malformed declarations block that work.
• Apply the spec workflow's large-scope decomposition rules only to the accepted scope actually selected.

For selected observable-surface work, validate only declared or evidenced surfaces. Configuration is not live-review evidence; a relevant but unusable surface is ENVIRONMENT-BLOCKED, and first-run expectations remain ACCEPTANCE-PENDING.

Run /changes-review --defer=whole-target and then /why-review after setup and selected work are complete. If no files changed, record that result without claiming a review of nonexistent changes.

Check root instructions and host mirrors only when those hosts/context files are installed or selected. Preserve user content; if Codex mirrors need regeneration, use the documented /ai-context-refresh completion handoff, or report the /sync-codex route when that handoff is unavailable.

Phase 5: Conditional Graph Refresh

Run graph work only when graph tooling is available and the project/task has code relationships for which graph coverage helps:

1. When applicable, Spawn background /graph-code --mode=build sub-agent to run /graph-code --mode=build with an evidence-supported scope and return a concise outcome.

Rules:

• When graph work is selected, run it in the required background/sub-agent lane and track it to a returned result or an explicit tool/dependency blocker.
• Existing graph presence is not enough by itself to select a refresh; use the active task's scope and graph freshness evidence.
• When graph tooling or relevant code relationships are absent, record why graph work was skipped.

Output

Report:

• Folder classification: empty, greenfield, existing, or already initialized.
• Files created/updated/skipped: configured project config, always-on and selected reference docs, applicable root instructions and host mirrors.
• Lower-level skills/scripts invoked.
• Selected reference scans and spec work: outcome plus evidence, or an explicit applicability-based skip/deferral for each.
• Always-on lessons.md and docs-index-reference.md: configured paths and health, independently of task-specific referenceDocs.
• Experience applicability matrix: each configured or observed surface, intended outcome, exercise/inspection capability, evidence status, acceptance state, and limitation/NOT-APPLICABLE/ENVIRONMENT-BLOCKED reason.
• Final review skill calls: /changes-review, /why-review, each with outcome and evidence.
• Graph refresh: /graph-code --mode=build sub-agent outcome when selected, or evidence-backed skip.
• Spec workflow: invoked mode (init-full, audit, update), profile validation result, or evidence-backed deferral reason and next trigger.
• Verification commands and results.
• Remaining manual action, especially any /sync-codex step that did not run.

<!-- PROTOCOL-GUIDES:START -->

Protocol guides — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.

• output-quality-principles — Readable guidance and verified contents for long skill/doc files; writing, updating or auditing a skill or reference document, or another Markdown artifact over 200 lines → .claude/skills/shared/protocols/output-quality-principles.md

<!-- PROTOCOL-GUIDES:END --> <!-- SYNC:output-quality-principles:reminder -->

IMPORTANT MUST ATTENTION lead with useful guidance and readable priorities; preserve action-changing conditions/numbers and required structures. When writing, updating or auditing Markdown skill/doc content, verify top, heading-linked contents over 200 lines (stricter owner thresholds remain); refresh after edits and report gaps in read-only audits. Remove report bulk; judge semantic value rather than word counts.

<!-- /SYNC:output-quality-principles:reminder -->

Closing Reminders

MUST ATTENTION selected review setup delegates evidence → preview → accepted protected merge → validation to project-config; initialize without acquiring review tools.

IMPORTANT MUST ATTENTION Goal: any agent, with or without hooks, reaches a verified project-context state before project-specific work.

MUST ATTENTION Protocols in force (concise digest of the SYNC/shared blocks this skill carries):

• Parallel Sub-Agent Dispatch: Tag tasks PAR/SEQ, group PAR into disjoint-write-set waves, spawn each wave in ONE message, barrier before advancing.

IMPORTANT MUST ATTENTION use /project-init as the unified missing-context route; lower-level skills remain implementation steps. IMPORTANT MUST ATTENTION create task-plan rows for required setup and final reviews; add scan, spec, surface, root-sync, and graph tasks only when evidence selects them. IMPORTANT MUST ATTENTION the configured project-config file and non-empty project.name are required; omitted optional properties are valid unless a declared property is invalid. IMPORTANT MUST ATTENTION keep absent referenceDocs separate from an explicit selection: absent uses the resolver baseline (possibly empty) plus evidenced capability docs; explicit arrays, including [], remain exact. Always-on lessons/index inputs are ensured independently. IMPORTANT MUST ATTENTION run /scan-all only when applicable selected/evidenced scan targets exist; run /workflow-code-to-spec only for an existing canonical owner or accepted capability scope. IMPORTANT MUST ATTENTION when both scan and spec work are selected, run them as parallel siblings when supported and wait for both outcomes; otherwise run only selected tasks. IMPORTANT MUST ATTENTION preserve valid native specArtifacts; absence uses strict TC/Section-8 defaults when spec work is selected, while an invalid declaration blocks spec work. IMPORTANT MUST ATTENTION run /graph-code --mode=build only when graph tooling exists and relevant code relationships or task needs justify it; record an evidence-backed skip otherwise. IMPORTANT MUST ATTENTION run /changes-review --defer=whole-target and then /why-review after setup and selected work; report no-change explicitly. IMPORTANT MUST ATTENTION record explicit blocker for any unavailable required skill/tool; silent skip is not completion. IMPORTANT MUST ATTENTION preserve user-authored root instruction files; do not overwrite project-only content. IMPORTANT MUST ATTENTION rerun Phase 0 after every setup phase because the next route depends on current evidence. IMPORTANT MUST ATTENTION keep reusable setup logic project-neutral; project-specific facts belong in config/reference docs.

Anti-Rationalization:

Evasion	Rebuttal
"Config exists, skip planning"	Create full task plan first; missing-context setup drifts without visible rows.
"A valid minimal config looks incomplete"	Require only non-empty project.name; derive optional sections from evidence.
"Partial reference selection needs the full registry"	Preserve the explicit selection; the catalog is metadata, and always-on inputs are separate.
"Package names are enough to define spec scope"	Require an existing canonical owner or accepted scope before creating specs or test cases.
"Graph already exists"	Select refresh from graph freshness and task relevance; do not turn graph support into a setup prerequisite.
"Review is enough"	Run /changes-review, /why-review, and all applicable focused verification before reporting.