Project Init

Project Init

Purpose

Initialize or refresh project-local development context for Project Develop Copilot.

This skill creates a usable, stable .llm-wiki project-context structure, discovers modules conservatively, records tool bridge markers, and migrates legacy docs/ai-coding as read-only source context. It follows the project/user language context for generated prose and does not modify production code.

It also produces a context completion plan. Init should not imply the agent fully understands every module. Whole-repository init normally reaches project navigation readiness, then guides the user to complete source-backed scoped contexts before feature or bug work.

When to Use

Use when the router or user needs to:

• adopt a repository into Project Develop Copilot
• create .llm-wiki for the first time
• refresh stale project context
• discover modules and service boundaries
• prepare tool bridge markers such as existing .codegraph/
• migrate useful legacy docs/ai-coding context into .llm-wiki

When Not to Use

• Do not use for ordinary feature development after project context already exists.
• Do not use for bug diagnosis unless the project context is missing or stale.
• Do not use for source ingest of one PRD/log/PDF; use project-ingest.
• Do not use to edit production code.

Owned Gates

• Context Recovery Gate
• Finish Sync Gate when init produces wiki starters, artifact entries, or dashboard starter/projection files

Required First Check

1. Resolve project_root.
2. Resolve optional shared references from ../references/ or local references/. If domain-skill-contract.md, progress-dashboard.md, or progress-dashboard-template.html is missing, continue in degraded mode using the minimum rules in this skill; report the missing deep references and skip template-dependent dashboard generation unless a safe starter can be produced.
3. Report root evidence before writing:
   • user-provided path
   • current working directory
   • .git
   • root build file
   • docs/ai-coding
   • existing .llm-wiki
   • confidence: high, medium, or low
4. If root confidence is medium or low, ask the user to confirm before writing .llm-wiki.
5. Check whether .llm-wiki exists.
6. Decide init vs refresh, then resolve bootstrap_mode: use automatic-minimal only for a missing-wiki handoff from the router or child; use explicit-full for a user-requested init, adopt, or refresh.
7. Check for legacy docs/ai-coding/.
8. Treat graph outputs as optional supporting context only when explicitly active or requested.
9. Preserve useful existing .llm-wiki content before writing updates.
10. Detect the project language before writing generated prose:

• prefer the user conversation language when clear;
• otherwise prefer the dominant language of existing project docs and legacy context;
• keep code identifiers, paths, command names, status ids, and protocol terms unchanged;
• if the project is bilingual, use the user-facing language for prose and preserve technical English terms inline.

Bootstrap Return Contract

When the router enters project-init because a business repository has no .llm-wiki/:

• Accept and preserve pending_intent and pending_primary_stage from the Context Handoff.
• Accept bootstrap_mode: automatic-minimal; do not silently promote it to an explicit full init.
• Return the achieved initialization_level, remaining context gaps, and evidence-backed next_gate.
• Keep the original user goal pending; do not replace it with a generic initialization task.
• A Level 1 or Level 2 result must not automatically invoke project-develop, project-fix, or another pending stage. Return control to the router, which decides whether the next gate is scoped context completion, work definition, or the preserved stage.
• Do not claim that creating the standard wiki skeleton proves feature readiness or full project understanding.

Automatic Minimal Bootstrap Mode

Use bootstrap_mode: automatic-minimal only when the router or a wiki-backed child discovers that <project_root>/.llm-wiki/ is absent while preserving another pending_primary_stage.

• This mode writes only under <project_root>/.llm-wiki/**.
• Create the standard Wiki structure, starter content, dashboard, and vendored Doctor files under .llm-wiki/tools/** when their scaffold is available.
• It must not create or modify .gitignore, .pre-commit-config.yaml, .github/workflows/llm-wiki-doctor.yml, or any other project-root file.
• Return those deferred project-root files as root_integrations_pending; do not treat them as initialization failures and do not block the preserved pending stage solely because they are absent.
• Do not ask for confirmation merely because the pending child is read-only by default. Ask only when the user explicitly forbids writes or root confidence is medium or low.

Explicit Full Init / Refresh Mode

Use bootstrap_mode: explicit-full when the user explicitly asks to initialize, adopt, install, or refresh project context.

• This mode may install or merge the project-root integrations .gitignore, .pre-commit-config.yaml, and .github/workflows/llm-wiki-doctor.yml.
• Preserve project-owned integration files: merge safely when obvious, write an .example, or report a manual merge action instead of overwriting.
• Explicit full init retains the standard .llm-wiki/** creation and refresh behavior.

Core Process

Read as needed:

• ../references/north-star.md
• ../references/lifecycle-gates.md
• ../references/domain-skill-contract.md
• ../references/tool-bridge.md
• ../references/legacy-ai-coding-migration.md
• ../references/progress-dashboard.md
• ../references/progress-dashboard-template.html

Reference availability policy:

• Shared references are deep references, not startup requirements.
• Do not stop solely because ../references/ is missing.
• In degraded mode, still perform root evidence checks, create/preserve the standard .llm-wiki structure, and write conservative starter files.
• If the dashboard template is unavailable, do not invent unsupported dashboard data; create only a minimal placeholder or report that dashboard generation was skipped.

Workflow:

1. Resolve project root.
2. Inspect project markers under the resolved project root only: .git, build files, docs/, .llm-wiki/, legacy docs/ai-coding/, and explicitly active graph outputs.
3. Create missing .llm-wiki standard directories and starter files. Do not use an ad-hoc minimal layout when the project development lifecycle expects the standard structure.
4. Ensure the standard .llm-wiki directory structure exists; create missing directories without deleting extra existing directories.
5. Install or refresh the LLM Wiki Doctor scaffold from ../assets/llm-wiki-doctor-scaffold/ into the consuming project when available. In automatic-minimal, copy only .llm-wiki/tools/**; in explicit-full, also install or merge the project-root integrations.
6. Create or update .llm-wiki/modules/index.md.
7. Create .llm-wiki/modules/<scope>/ only for user-selected or clearly active scopes that need source-backed context.
8. Detect modules conservatively from build files and top-level service directories.
9. Mark modules as active, reference-only, discovered, or unknown.
10. Do not automatically record .codegraph/, graphify-out/, GRAPH_REPORT.md, or generated graph files merely because they exist; register them only when user-requested, already maintained in .llm-wiki, or explicitly active in project docs.
11. Summarize legacy docs/ai-coding into .llm-wiki without deleting or rewriting legacy files.
12. Create .llm-wiki/dashboard/progress.html from ../references/progress-dashboard-template.html when missing, using the detected project language for visible labels when practical.
13. Register the dashboard in .llm-wiki/artifacts/index.md when the artifact registry exists; if the registry does not exist yet, create the standard artifact registry starter.
14. Produce a context completion plan with recommended scoped contexts, missing architecture/source-map facts, source evidence, and suggested next action.
15. Preserve existing statuses unless evidence or user instruction changes them.
16. Write a .llm-wiki/log.md entry.
17. Return a concise handoff with the current init completion level, preserved pending route, readiness gaps, and next gate.
18. If this is a refresh, never downgrade an existing richer wiki structure to a smaller skeleton.

Language Policy

Generated .llm-wiki prose must follow the actual project and user language context.

• If the user asks in Chinese and project docs are Chinese or bilingual, write wiki prose in Chinese.
• If the repository docs are primarily English and the user has not asked for another language, write prose in English.
• Preserve exact code identifiers, module names, paths, commands, protocol terms, status ids, and lifecycle level names.
• For mixed-language projects, use the user's language for explanations and keep technical English terms inline where that is clearer.
• Do not silently fall back to English templates when the surrounding context is Chinese.

Standard .llm-wiki Structure

A project init must create or preserve this standard structure. Some directories may contain only a README.md or .gitkeep starter during init, but the directories themselves should exist so later lifecycle skills have stable targets.

.llm-wiki/
  README.md
  log.md
  project/
  requirements/
  ingest/
  modules/
  sources/
  artifacts/
  cross-refs/
  project-graph/
  tools/
  dashboard/
  session-digests/
  migration/
  working-context/
  decisions/
  verification/
  handoff/

Minimum starter files:

• .llm-wiki/README.md: root evidence, init mode, current level, and key artifacts.
• .llm-wiki/project/overview.md: project-level orientation and source-of-truth notes.
• .llm-wiki/requirements/README.md: requirement intake/status landing area.
• .llm-wiki/ingest/README.md: imported PRD/log/doc/source-proxy landing area.
• .llm-wiki/modules/index.md: module inventory table.
• .llm-wiki/modules/<scope>/README.md: scoped-context landing area only for selected or clearly active scopes.
• .llm-wiki/sources/registry.md: source and supporting-context registry.
• .llm-wiki/artifacts/index.md: specs, plans, reports, verification notes, generated pages, and dashboard registry.
• .llm-wiki/cross-refs/index.md: cross-project pin layer; stores team-confirmed entry points that reference project-graph/edges.md by edge_id only.
• .llm-wiki/project-graph/edges.md: unique cross-project relationship fact table.
• .llm-wiki/project-graph/candidates.md: candidate/discovered relationship table; candidates do not drive decisions.
• .llm-wiki/project-graph/scan-report.md: graph scan summary placeholder plus retained Archived Candidates audit section.
• .llm-wiki/tools/llm_wiki_doctor.py: project-vendored deterministic validator installed from the skill scaffold.
• .llm-wiki/tools/VERSION: source path and commit metadata for the vendored validator.
• .llm-wiki/dashboard/progress.html: static project progress dashboard generated from the skill template.
• .llm-wiki/session-digests/README.md: recallable Session Digest landing area for historical chat/session summaries.
• .llm-wiki/migration/legacy-ai-coding.md: legacy docs/ai-coding migration index when present.
• .llm-wiki/working-context/README.md: active task scratch area.
• .llm-wiki/decisions/README.md: durable project decisions landing area.
• .llm-wiki/verification/README.md: verification commands, gaps, and evidence landing area.
• .llm-wiki/handoff/README.md: handoff summaries and return handoffs.
• .llm-wiki/context-completion-plan.md: recommended scoped contexts and missing facts.

Refresh rules:

• Preserve existing directories and richer files even if they are not listed above.
• Add missing standard directories/files without flattening, renaming, or deleting user-created structure.
• Create or preserve .llm-wiki/cross-refs/index.md with the pin-layer Cross-Project Integration Points template when missing.
• Create or preserve .llm-wiki/project-graph/edges.md, .llm-wiki/project-graph/candidates.md, and .llm-wiki/project-graph/scan-report.md with empty templates when missing.
• Always install or refresh .llm-wiki/tools/llm_wiki_doctor.py and .llm-wiki/tools/VERSION from the scaffold so each consuming project has local machine-check entry points.
• In explicit-full only, install or refresh .pre-commit-config.yaml and .github/workflows/llm-wiki-doctor.yml. Do not silently overwrite project-owned files; merge safely when obvious, write a .example file, or report a manual merge action.
• Refresh .llm-wiki/tools/llm_wiki_doctor.py only when it was scaffold-generated or when the user confirms replacement.
• In explicit-full only, ensure .gitignore contains .llm-wiki/registry.local.json, .llm-wiki/cross-refs/registry.local.json, and .llm-wiki/project-graph/scan-state.local.json exactly once so local project-path mappings and scan state do not enter git.
• Do not create .llm-wiki/registry.local.json or .llm-wiki/cross-refs/registry.local.json during init unless the user provides a remote project path and confirms storing it as local-only configuration.
• Do not scan external projects during project-init; scanner is an optional later project-maintain graph-scan flow.
• If the user initializes a Base Graph repo, stop ordinary business-project init and route to project-base-init. Do not create Base files from project-init.
• Create or preserve .llm-wiki/session-digests/ for confirmed Session Digests. Do not scan it as raw source material; treat it as recall context by default, not project truth.
• When .llm-wiki/session-digests/ exists, include it in context discovery for recall and duplicate avoidance. Do not promote digest items to requirement, bug, module, Flow Record, dashboard, scope, or verification truth without explicit Lifecycle Promotion confirmation.
• If an older project uses a different but richer lifecycle layout, record it in project/overview.md or sources/registry.md and ask before reorganizing.
• If .llm-wiki/dashboard/progress.html already exists, preserve its layout and update only the structured data/status sections needed by progress-dashboard.md.

Mode / Entry Selection

Inputs

• project root or repository path
• existing .llm-wiki
• build files and top-level directories
• legacy docs/ai-coding
• existing .codegraph or graph output paths
• user-selected active modules when provided

Outputs

Report:

Project root:
Mode:
Created:
Updated:
Preserved:
Modules:
Codegraph context:
Legacy migration:
Context completion level:
Recommended scoped contexts:
Open questions:
Next action:

Module index minimum:

| Module | Path | Type | Context | Status | Notes |
|---|---|---|---|---|---|

Cross-project refs minimum:

# Cross-Project Integration Points

| id | edge_id | local_entry | why_pinned | owner_note |
|---|---|---|---|---|

## Notes

- This is a pin layer only. Store facts in `.llm-wiki/project-graph/edges.md`.
- Do not copy `contract_summary`, `verification_status`, `last_verified`, `remote_project`, or `remote_anchor` here.

Project Graph edges minimum:

# Project Graph Edges

| edge_id | fingerprint | type | source | from_project | from_anchor | to_project | to_anchor | contract_summary | verification_status | last_verified |
|---|---|---|---|---|---|---|---|---|---|---|

## Notes

- This is the unique cross-project relationship fact table.
- Manual registration defaults to `verification_status: draft`.
- Do not write `stale`; derive staleness from `last_verified`.

Project Graph candidates minimum:

# Project Graph Candidates

| candidate_id | candidate_fingerprint | relation | source | local_anchor | remote_project | remote_anchor | evidence | confidence | status | edge_id | discovered_at | last_seen |
|---|---|---|---|---|---|---|---|---|---|---|---|---|

## Notes

- Candidates are clues only and must not drive fix or development decisions.
- `source` is `scan` or `manual`.
- New candidates default to `status: pending`.
- `pending` scan-origin candidates older than `default_candidate_pending_days` are archived by `project-maintain`, not by query/fix/develop.

Project Graph scan report minimum:

# Project Graph Scan Report

- scanned_at:
- scanner_version:
- scanned_projects:
- scan_scope:
- read_only_scope:
- new_candidates:
- updated_candidates:
- suppressed_candidates:
- changed_edges:
- stale_edges:
- blocked_items:

## Notes

-

## Archived Candidates

| candidate_fingerprint | relation | local_anchor | remote_project | remote_anchor | last_seen | archived_on | reason |
|---|---|---|---|---|---|---|---|

<!-- Keep this section across scan-report refreshes. De-duplicate archived rows by candidate_fingerprint. -->

Base Graph delegation:

• Dedicated Base Graph repositories are initialized by project-base-init, not ordinary project-init.
• If this skill is invoked directly for a Base Graph repo, explain the route mismatch and hand off to project-base-init.
• Do not create Base manifest.json, project-catalog.md, overview.md, shared-edges.md, relation-policy.md, or Base registry files from project-init.

Context Handoff

When called by the root router, accept:

## Context Handoff

- project_root:
- lifecycle_session:
- user_intent:
- pending_intent:
- pending_primary_stage:
- active_sources:
- active_scope:
- read_only_scope:
- candidate_scope:
- excluded_scope:
- current_gate:
- requested_stage_or_bridge:
- constraints:

Return Handoff

Return:

## Return Handoff

- project_root:
- stage_or_bridge_used: project-init
- result_summary:
- changed_assumptions:
- recommended_scope_changes:
- artifacts:
- verification_notes:
- lifecycle_updates_needed:
- pending_intent:
- pending_primary_stage:
- initialization_level:
- next_gate:

Boundaries

• Do not modify production code.
• Do not delete, move, or rewrite legacy docs/ai-coding.
• Do not deep-read every module in a monorepo.
• Do not treat generated AI docs as source of truth.
• Do not overwrite existing .llm-wiki summaries without preserving useful user or agent decisions.
• Do not generate English prose by default when the project/user context is Chinese or another non-English language.
• Do not omit standard lifecycle directories such as requirements/, ingest/, project/, modules/, decisions/, verification/, or handoff/ during init.
• Do not require codegraph generation.
• Do not silently switch into a child module just because it has richer build files; record it as a module under the chosen root unless the user confirms it is the root.
• Do not write facts from another checkout or previous conversation into the current .llm-wiki.
• Do not route directly to feature development as the default init next action when scoped module context is missing.
• Do not create a separate project-root scope-context/, contexts/, or new docs/ai-coding/<scope>/ tree as the primary context store. Project-level context belongs in .llm-wiki; scope-level context belongs under .llm-wiki/modules/<scope>/; task-level context belongs in .llm-wiki/working-context/<change-id>.md.

Init Completion Levels

Whole-repository init should normally finish at Level 1 or Level 2 unless the user explicitly selects a scope to complete.

Context Completion Plan

After global project context exists, recommend scoped contexts using this shape:

| Scope | Why | Active Paths | Reference Paths | Status | Missing Facts | Suggested Next Action |
|---|---|---|---|---|---|---|

Good candidates include modules with existing docs/ai-coding/<scope>/, protocol-heavy modules, deployment owners, persistence-contract modules, cross-service API owners, and recurring feature areas from user/project docs.

Do not claim a recommended scope is feature-ready until source-backed architecture and source maps exist.

Wrong-Root Recovery

If the user corrects the project root after .llm-wiki was written:

1. Treat it as a blocker.
2. Stop using facts from the wrong root.
3. Initialize or refresh .llm-wiki under the corrected root.
4. Verify the corrected wiki contains no obvious foreign project names, module names, or paths.
5. Report wrong wiki locations separately and ask before deleting them.
6. Run project-review style checks for wiki drift, scope drift, and unrelated writes before claiming recovery is complete.

Common Mistakes

• Turning init into full codebase analysis.
• Using English boilerplate in a Chinese project or conversation.
• Creating a smaller ad-hoc .llm-wiki layout that breaks lifecycle skills expecting standard directories.
• Marking every discovered module active.
• Rewriting existing wiki content destructively.
• Treating legacy AI docs as authoritative.
• Registering stale graph output when the user said to ignore it.
• Claiming full feature readiness after only project navigation init.