@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-core/skills/workflow-project-context/SKILL.md

@@ -0,0 +1,819 @@
+---
+name: workflow-project-context
+description: "Use when a new or existing project needs .planning initialization, repository discovery, project context, navigation files, or rule-package setup."
+---
+
+## Legacy Command Metadata
+
+Original slash-command metadata retained only as workflow invocation guidance.
+
+```yaml
+argument-hint: '[--auto]'
+user-invocable: true
+pattern: inversion+generator+reviewer
+resumable: true
+state-file: .planning/STATE.md
+allowed-tools:
+- Read
+- Bash
+- Write
+- Glob
+- Grep
+- ask
+```
+
+# Project Initialization
+
+Initialize project context only. Do not create requirements, roadmap, research files, commits, tags, or Git repositories unless the user explicitly asks.
+
+## Outputs
+
+Always create or update:
+
+- `.planning/PROJECT.md` — project facts, structure, navigation, constraints, and decisions
+- `.planning/STATE.md` — initialization state, project locations, scan status, and next recommended step
+- `.planning/navigation/INDEX.md` — codebase registry: maps each codebase to its navigation file, plus rule package index and downstream read contract
+- `.planning/navigation/{name}.md` — one file per codebase: framework, entries, conventions, commands (name comes from user-provided codebase name)
+- `.planning/code-index/` — machine code intelligence index location; generated by `workflow-code-index` by default unless fast mode skips it
+- `.context/spec/design/` — conditional frontend design rule package; installed after code-index for projects with frontend codebases
+- `.planning/project-context-run.json` — current-run evidence: run identity, code-index status, dynamically discovered depth specs, source paths, and source fingerprints
+- `.context/spec/index.md` — generated technical specification registry: maps stack profiles and codebase specs
+- `.context/spec/stacks/{stack_key}.md` — deduplicated stack-level technical rules for each detected stack profile
+- `.context/spec/frontend/{name}.md` / `.context/spec/backend/{name}.md` — codebase-specific technical rules generated from explicit rules and observed conventions
+- `.planning/rules/INDEX.md` — project rule index, the first file downstream skills read for project-specific conventions
+- `.planning/execution-contract.md` — layer order, TDD strategy, codegen and verification gates
+- `.planning/toolchain.md` — consolidated build, test, lint, mock, and migration commands
+
+Also record existing project rule package locations when found (these are accumulated over time, not created during initialization):
+
+- `.planning/lessons/`
+- `.planning/milestones/`
+- `.planning/requirements/`
+- `.context/spec/`
+- `.context/workflow/`
+- `.context/lessons/`
+- root `AGENTS.md`, `CLAUDE.md`, or equivalent instruction files
+
+Do not create by default:
+
+- `.planning/REQUIREMENTS.md`
+- `.planning/ROADMAP.md`
+- `.planning/research/`
+- `.planning/config.json`
+
+## Pattern
+
+This skill combines three patterns:
+
+- **Inversion**: ask for required project locations before scanning or generating files.
+- **Generator**: fill templates from `assets/`.
+- **Reviewer**: check the generated files against `references/navigation-guide.md`.
+
+Load bundled resources only when needed:
+
+- Read `assets/project-initialization-template.md` before writing `PROJECT.md`.
+- Read `assets/codebase-navigation-template.md` before writing each codebase navigation file.
+- Read `assets/navigation-index-template.md` before writing `.planning/navigation/INDEX.md`.
+- Read `assets/context-spec-index-template.md` before writing `.context/spec/index.md`.
+- Read `assets/stack-spec-template.md` before writing each `.context/spec/stacks/{stack_key}.md`.
+- Read `assets/codebase-backend-spec-template.md` before writing each backend/service `.context/spec/backend/{name}.md`.
+- Read `assets/codebase-frontend-spec-template.md` before writing each frontend `.context/spec/frontend/{name}.md`.
+- Read `assets/spec-templates/backend/{template}.md` before writing each backend depth spec file.
+- Read `assets/spec-templates/frontend/{template}.md` before writing each frontend depth spec file.
+- Read `assets/agents-md-template.md` before writing root `AGENTS.md`.
+- Read `assets/context-domain-index-template.md` before writing `.context/spec/frontend/index.md`, `.context/spec/backend/index.md`, and `.context/spec/design/index.md`.
+- Read `assets/state-template.md` before writing `.planning/STATE.md`.
+- Read `assets/execution-contract-template.md` before writing `.planning/execution-contract.md`.
+- Read `assets/toolchain-template.md` before writing `.planning/toolchain.md`.
+- Read `assets/rules-index-template.md` before writing `.planning/rules/INDEX.md`.
+- Read `assets/run-manifest-template.json` before writing `.planning/project-context-run.json`.
+- Read `references/navigation-guide.md` before scanning code and again before final review.
+- Run `scripts/validate_initialization.py` as the final completion gate.
+
+## Argument Handling
+
+Parse `$ARGUMENTS` before Step 1:
+
+- `--auto`: non-interactive initialization. If codebase locations are not provided, treat the current workspace as a single codebase, scan boundedly, and mark anything not found as `待确认` or `pending`. Do not block on project-name or business-context questions; infer what is obvious and record missing facts.
+- `--fast` / `--skip-code-index`: fast initialization. Generate project context, navigation, specs, and rules, but skip Step 6.5 (code-index) and mark code-index as skipped in `STATE.md`, `PROJECT.md`, navigation INDEX, and rules INDEX. This is the ONLY condition under which code-index may be skipped. Without this flag, code-index is REQUIRED regardless of whether `.planning/` already exists.
+- `--with-code-index`: compatibility flag for explicit full initialization. This is the default behavior; after navigation generation, run Step 6.5 to build/validate/audit `.planning/code-index/`, then carry its status into the remaining generated context and rule files.
+- Other text may be used as project-name or project-context hint when it is not a path.
+
+At invocation start, before scanning or writing:
+
+1. Generate a unique `run_id`.
+2. Capture `run_started_at` as an ISO-8601 UTC timestamp.
+3. Set mode to `full`, or `fast` only when one of the explicit skip flags is present.
+4. Carry the same `run_id`, `run_started_at`, `code_index_status`, and skip reason into all templates and `.planning/project-context-run.json`. Use `none` when full mode has no skip reason.
+
+In non-auto mode, ask the intake questions below.
+
+## Existing Planning Update Policy
+
+If `.planning/` already exists:
+
+1. Read existing `.planning/PROJECT.md`, `.planning/STATE.md`, and `.planning/navigation/*.md` before writing.
+2. Preserve user-authored business context, constraints, key decisions, and missing information unless the user explicitly asks to replace them.
+3. Refresh only machine-derived fields. This includes: detected paths, frameworks, entries, commands, scan status, navigation index, rule package files (execution-contract.md, toolchain.md, rules/INDEX.md), **all currently discovered depth spec files (Step 7.4)**, and **code index (Step 6.5)**. The presence of existing output files does NOT exempt a step from re-execution — machine-derived fields must be regenerated to reflect current codebase state.
+4. If provided codebase locations differ from existing records, record the change in `STATE.md` under `Change Log`.
+5. Never delete existing planning files during initialization. Preserve user-authored content in execution-contract.md and toolchain.md when refreshing machine-derived fields.
+
+## Step 1 — Intake Gate
+
+Before any initialization, ask for all codebases in the project:
+
+```text
+请提供项目涉及的所有代码库。每个代码库需要三个信息：
+  - 地址：本地路径或 Git 仓库 URL；如果在当前目录，请写”当前目录”
+  - 类型：描述这个代码库的角色（如：C端前端、后台前端、后端服务、定时任务、SDK等）
+  - 名称：简短的标识名称，用作导航文件名（如：union-next、saas-admin、union-api）
+
+示例（3个代码库的项目）：
+  1. byn-web/packages/union-next   C端前端    union-next    联盟客户侧
+  2. byn-web/packages/saas-admin   后台前端   saas-admin     运营后台
+  3. union/                        后端服务   union          联盟核心服务
+
+如果只有1个代码库，写1行即可。
+```
+
+Do not proceed until at least one codebase is provided, except in `--auto` mode where the current workspace is used as a single codebase with `待确认` type and name inferred from the directory.
+
+Accepted values per codebase:
+- **Path**: local path (`./frontend`, `/path/to/web`), Git URL (`https://...`, `git@...`), current workspace (`当前目录`, `same repo`, `.`)
+- **Type**: freeform text describing the codebase's role. Common values: `C端前端`, `后台前端`, `后端服务`, `定时任务`, `SDK`, `公共组件库`, `移动端` — but these are not hardcoded; use whatever the user provides.
+- **Name**: short identifier safe as a filename segment (letters, digits, hyphens). Used for `.planning/navigation/{name}.md`.
+
+If a Git URL is provided, record it. Ask before cloning; do not clone automatically.
+
+Record the codebase list for use in Step 3 (scan) and Step 6 (generate navigation files).
+
+## Step 2 — Minimal Project Questions
+
+Ask only what cannot be inferred from code:
+
+1. Project name
+2. What the product/system does
+3. Primary users or business domain
+4. Non-negotiable constraints, if any
+
+If the user says these are unknown, continue and mark them as `待确认`.
+
+## Step 3 — Structure Scan (Four-Phase)
+
+Read `references/navigation-guide.md`. Run the following four phases for EACH codebase from Step 1. Each phase has its own scan depth, output, and gate. Do not skip phases.
+
+Exclude generated/dependency directories in all phases: `node_modules`, `dist`, `build`, `.next`, `.nuxt`, `target`, `vendor`, `.git`, `coverage`.
+
+### Step 3a — Directory Map (Mandatory)
+
+Scan the codebase's top-level and second-level directory layout. This is the factual layer — what directories exist and what they contain.
+
+Scan method:
+```
+1. rg --files from codebase root → extract top-level and second-level directories
+2. Identify key manifest/config files: package.json, go.mod, Makefile, Dockerfile, README
+3. For each directory, infer purpose from file names and README content
+4. Do NOT read source files in depth — only directory names and manifests
+```
+
+Output (write to `{name}.md` → `## Structure → ### Directory Map`):
+- ASCII directory tree (top-level + second-level)
+- Table: Directory | Purpose | Notes
+
+Gate: every top-level and second-level directory is listed with a purpose (one sentence, inferred from file names is acceptable). Key entry files (main.go, main.ts, router files, handler files) are identified.
+
+### Step 3b — Call Chain Map (Mandatory)
+
+Trace the call chains through the codebase. This is the connectivity layer — how code connects across directories.
+
+**Dual-path routing** (decide before scanning):
+
+```
+For each codebase, check if a rule file exists in this order:
+  1. .cursorrules within the codebase root
+  2. AGENTS.md / CLAUDE.md at project root or codebase root
+
+If a rule file EXISTS → Path A: Conventions first
+  1. Execute Step 3c first to extract conventions
+  2. Use extracted conventions to guide call chain tracing
+  (e.g., if convention says "handler→service→repository→dao", follow that pattern)
+
+If NO rule file → Path B: Call chain first
+  1. Trace call chains from entry points by following imports/method calls
+  2. The traced patterns will feed into Step 3c for convention extraction
+```
+
+Scan method:
+
+**Backend-type codebases** (type contains "后端" or "服务"):
+```
+1. Find handler files (look for route registration patterns):
+   - Go: files with RegisterRoutes, gin routes, or echo routes
+   - Java: @RestController, @RequestMapping
+   - Node: router files, controller files
+2. For each handler, extract registered routes and the methods they call
+3. Follow the call chain: handler method → service method → repository method → dao method
+4. Find job/scheduler files (look for cron patterns, @Scheduled, job registration):
+   - Extract cron expression or trigger condition
+   - Trace the job's call chain into services
+5. Find external integration packages/directories:
+   - Identify outbound HTTP clients, gRPC clients, message queues
+```
+
+Output (write to `{name}.md` → `## Structure → ### Call Chain Map`):
+- `#### API Modules` table: Route Group | Handler | Routes | Service → Repository → DAO
+- `#### Scheduled Jobs` table: Job | Cron | Trigger Type | Call Chain | Notes
+- `#### External Integrations` table: Integration | Path | Direction | Notes
+
+Gate: every handler file identified in 3a has its call chain traced (at minimum: handler→service). Every job file has its trigger and target service identified.
+
+**Frontend-type codebases** (type contains "前端"):
+```
+1. Read router configuration → extract all routes with their page components
+2. For each page component, read the file and extract:
+   - Imported child components (from page-private and common components)
+   - Imported composables/hooks
+   - API calls (direct or through composables)
+3. For each composable, extract:
+   - API client methods called
+   - State shape (reactive/ref/store)
+4. Build the route→component→composable→API call tree
+```
+
+Output (write to `{name}.md` → `## Structure → ### Call Chain Map`):
+- `#### Route-Component Map` table: Route | Page Component | Child Components | Composables | API Calls
+- `#### Data Flow` table: Composable / Store | API Client | State Shape | Consumed By
+
+Gate: every route has its page component and at least the first-level child components listed. Every composable used by more than one component is in the Data Flow table.
+
+### Step 3c — Conventions (Mandatory)
+
+Extract the coding conventions that govern this codebase. This is the rules layer — how code should be written.
+
+**If Path A (rule file existed, 3c was already executed before 3b):**
+- The conventions extracted from .cursorrules / AGENTS.md were used to guide 3b.
+- Now cross-validate: did the actual code follow these conventions? If violations found, note them.
+
+**If Path B (no rule file, 3c runs after 3b):**
+- Infer conventions from the patterns observed during 3b call chain tracing.
+- If a pattern is consistent across all modules (e.g., every handler calls a service interface), record it as a convention.
+- If patterns are inconsistent, record the dominant pattern and note the variations.
+
+Scan method:
+```
+1. If .cursorrules or AGENTS.md / CLAUDE.md exist, read them and extract:
+   - Layer/component hierarchy rules
+   - Naming conventions
+   - Data conversion rules (VO↔Domain↔Model)
+   - Error handling patterns
+   - Code generation or documentation rules
+2. If no rule file, infer from 3b observations:
+   - Consistent directory patterns → layer convention
+   - Consistent method signatures → interface convention
+   - Consistent import patterns → dependency direction
+3. Mark any convention as "推断" (inferred) when not backed by an explicit rule file.
+```
+
+Output (write to `{name}.md` → `## Structure → ### Conventions`):
+
+**Backend-type**: Table with columns Category | Rule | Source
+Categories: Layer order, Conversion (VO↔Domain↔Model), Interface/DI, Error handling, Naming, Swagger/API docs
+
+**Frontend-type**: Table with columns Category | Rule | Source
+Categories: Component hierarchy, Data flow (composable/store), Route naming, Style/theme, API client, State management
+
+Source values: `{rule_file_name}` (explicit rule), `代码推断` (inferred from code patterns), or `待确认` (not observed).
+
+Gate: at least Layer order (backend) or Component hierarchy (frontend) is recorded. Inferred conventions are marked as `代码推断`, not as facts.
+
+### Step 3d — Stack Profile Extraction (Mandatory)
+
+Extract a normalized stack profile for each codebase. This is the dependency fingerprint layer: which runtime, framework, major versions, and key libraries govern the codebase.
+
+Scan method:
+```
+1. Read detected manifest files from 3a:
+   - Frontend/Node: package.json, pnpm-lock.yaml, yarn.lock, package-lock.json
+   - Python: pyproject.toml, requirements.txt, poetry.lock, uv.lock
+   - Go: go.mod
+   - Java/Kotlin: pom.xml, build.gradle, build.gradle.kts
+2. Extract only dependency names and versions needed to identify the stack profile:
+   - language/runtime
+   - primary framework and major version
+   - key libraries that materially change conventions (e.g., Ant Design, Zustand, FastAPI, Pydantic major version, SQLAlchemy vs SQLModel, Gin, GORM, Spring Boot)
+   - package manager/build tool
+   - test framework if detectable
+3. Compute a stable `stack_key` from:
+   language + framework + framework major version + key libraries
+   Examples: `python-fastapi-pydantic2-sqlalchemy`, `react-vite-antd`, `go-gin-gorm`
+4. Record manifest path and dependency fingerprint. A hash of the manifest is acceptable; otherwise list key dependency versions.
+```
+
+Output (write to `{name}.md` → `## Stack → ### Stack Profile`):
+- Table: Field | Value | Source
+- Required fields: language/runtime, framework, framework version, key libraries, package manager/build tool, test framework, manifest path, dependency fingerprint, stack_key
+
+Rules:
+- Do not merge different major versions or materially different key libraries into the same stack profile.
+- Do not put project-instance conventions into the stack profile. Stack profiles identify technology families; project-specific rules belong in codebase specs.
+- If a manifest exists but versions are ambiguous, record `待确认` for version and keep the manifest path.
+
+Gate: every local/scannable codebase has a stack profile. Remote/unavailable codebases may be `pending` with the known manifest or stack hint recorded.
+
+### After All Codebases — Project-Wide Sources
+
+After 3a/3b/3c/3d complete for all codebases, identify project-wide sources once:
+- `.planning/rules/`, `.planning/execution-contract.md`, `.planning/toolchain.md`, `.planning/lessons/`
+- `.planning/milestones/`, `.planning/requirements/`
+- `.context/spec/`, `.context/workflow/`, `.context/lessons/`
+- root `AGENTS.md` / `CLAUDE.md`
+
+Identify history model locations once:
+- primary: `.planning/milestones/`, `.planning/requirements/`, `.planning/lessons/`, `.planning/*/CONTEXT.md`
+- optional legacy: `features/`, `.context/lessons/`
+
+If a codebase location is unavailable or only a Git URL, write what is known and mark scan status as pending.
+
+Do not run `git init`.
+
+## Unknown Field Policy
+
+Avoid filling every table cell with `待确认`.
+
+- Required fields may be `待确认`: root, framework, app entry, router/controllers, commands.
+- Optional fields should be omitted from notes or summarized in `Missing Information` when not found.
+- If a whole area does not apply (e.g., frontend-type sections for a backend-only codebase), skip those sections in the codebase navigation file.
+- Each codebase gets its own navigation file regardless of type. There is no limit on the number of codebases.
+
+## Step 4 — Generate Base Directories
+
+Use this directory contract:
+
+```text
+.planning/
+├── PROJECT.md                 # stable project overview and decisions
+├── STATE.md                   # workflow memory and initialization status
+├── project-context-run.json   # current-run completion evidence
+├── navigation/
+│   ├── INDEX.md               # codebase registry — maps each codebase to its navigation file
+│   ├── {name1}.md             # per-codebase navigation (e.g., union-next.md)
+│   ├── {name2}.md             # per-codebase navigation (e.g., saas-admin.md)
+│   └── ...                    # one file for each codebase from Step 1
+└── rules/
+    └── INDEX.md               # rule source registry
+
+.context/
+└── spec/
+    ├── index.md               # generated spec registry and read order
+    ├── stacks/
+    │   └── {stack_key}.md     # deduplicated stack-level rules
+    ├── frontend/
+    │   ├── index.md
+    │   └── {name}.md          # per-frontend codebase rules
+    ├── backend/
+    │   ├── index.md
+    │   └── {name}.md          # per-backend/service codebase rules
+    └── design/
+        └── index.md
+```
+
+The number of navigation files matches the number of codebases provided in Step 1. Codebase specs are generated only for matching codebase types. No hardcoded frontend/backend split is assumed beyond the user's type labels and scan evidence.
+
+Do not create requirement, roadmap, research, config, or `.context/spec/workflow/` directories during initialization unless explicitly requested.
+
+## Step 5 — Generate PROJECT.md
+
+Load `assets/project-initialization-template.md` and fill every section.
+
+Required emphasis:
+
+- Project basics
+- Codebase locations (from Step 1)
+- Current structure
+- Links to navigation files (INDEX.md and per-codebase files)
+- Constraints
+- Key decisions
+- Project rule package locations
+- History model locations, with `.planning/milestones/`, `.planning/requirements/`, and `.planning/lessons/` as primary history and `.context/lessons/` / `features/` as optional legacy sources
+- Missing information
+
+If a field is unknown, write `待确认` rather than guessing.
+
+## Step 5.5 — Generate Root AGENTS.md
+
+Load `assets/agents-md-template.md` and write `AGENTS.md` at the project root.
+
+Fill from scan results:
+
+- **Project name**: from Step 2 or PROJECT.md.
+- **Codebase count and types**: from Step 1 codebase list.
+- **Rule entry**: `.planning/rules/INDEX.md` as entry point.
+- **Spec entry**: `.context/spec/index.md` if spec files were generated.
+
+Do not create `.claude/`, `.codex/`, or compatibility symlinks. OMP reads the
+project-local `.omp/AGENTS.md`; root `AGENTS.md` remains the portable project rule entry.
+
+## Step 6 — Generate Navigation Files
+
+Create `.planning/navigation/`.
+
+### 6.1 Generate INDEX.md
+
+Load `assets/navigation-index-template.md` and fill the Codebase Registry with every codebase from Step 1. Each row maps a codebase name to its path, type, role, scan status, and navigation file path.
+
+### 6.2 Generate per-codebase navigation files
+
+For EACH codebase from Step 1, load `assets/codebase-navigation-template.md` and generate `.planning/navigation/{name}.md`.
+
+Fill sections based on the codebase's user-provided type:
+
+**All codebases** fill these sections:
+- Identity (name, root, type, role, location, scan status)
+- Stack (framework, runtime, build tool, type-specific libraries, and Stack Profile from Step 3d)
+- Application Entry Points (app entry, and type-specific entries)
+- Commands (install, dev, build, test, lint, codegen)
+- Notes, Missing Information
+
+**Frontend-type codebases** (type contains "前端") additionally fill:
+- Stack: UI Library, State Management, Request Library
+- Entry Points: Router, Pages/Views, Layouts, API Client, Auth/Permission, Styles/Theme, Env Config
+- Structure: Directory Map (from 3a), Call Chain Map → Route-Component Map + Data Flow (from 3b), Conventions (from 3c)
+
+**Backend-type codebases** (type contains "后端" or "服务") additionally fill:
+- Stack: Database Access, API Style
+- Entry Points: Routes/Controllers, Middleware/Filters, Auth/Permission, Env Config, API Docs
+- Structure: Directory Map (from 3a), Call Chain Map → API Modules + Scheduled Jobs + External Integrations (from 3b), Conventions (from 3c)
+
+**Other types**: use the user-provided type to decide which sections to include. Prefer fewer sections with higher confidence over guessing.
+
+Rules:
+- Only write what was observed during scan. Do not invent paths or conventions.
+- If a section's data was not found during scan, write `待确认` for required fields or omit optional fields.
+- The `## Requirement-Relevant Areas` section is left with a placeholder `{{requirement_areas}}` — it will be filled by downstream skills as features are mapped to this codebase.
+- The `## Rule Sources` section points to `.planning/rules/INDEX.md` and lists only rule files found within this codebase's root (e.g., `.cursorrules`).
+
+## Step 6.5 — Code Index Refresh (REQUIRED)
+
+本步骤**必须**执行。仅当用户传入 `--fast` / `--skip-code-index` 时允许跳过，否则初始化视为未完成。已有输出、刷新场景或执行耗时均不构成豁免。
+
+In full mode, invoke `workflow-code-index` and run its deterministic implementation:
+
+```text
+devflow_code_index(action="scan")
+devflow_code_index(action="validate")
+devflow_code_index(action="audit")
+```
+
+All three commands must succeed. Do not treat pre-existing files as execution evidence. Step 10 verifies that these outputs were modified after `run_started_at`:
+
+- `.planning/code-index/index.sqlite`
+- `.planning/code-index/files.jsonl`
+- `.planning/code-index/symbols.jsonl`
+- `.planning/code-index/relations.jsonl`
+- `.planning/code-index/AUDIT.md`
+
+In fast mode, do not run the commands. Set `code_index_status` to `skipped`, record the explicit flag as `code_index_skip_reason`, and write the same current-run marker to `STATE.md`, `PROJECT.md`, navigation INDEX, and rules INDEX.
+
+After full-mode commands succeed, set `code_index_status` to `complete`, use skip reason `none`, and update the same marker in PROJECT and navigation INDEX. Rules INDEX and STATE receive it when generated in Steps 8 and 9.
+
+Do not require users to manually run Python when they invoked this skill.
+
+## Step 6.6 — Design Rule Package (Conditional Required)
+
+This step belongs to project initialization, not feature design. It runs **after the code index is available** and before the context-spec package is finalized.
+
+1. Determine applicability from the Step 1 codebase types and Step 3 scan evidence:
+   - If at least one local/scannable codebase is frontend-type, this step is required.
+   - If no frontend-type codebase exists, do not install UI recommendation assets; record `design_rule_pack.status: not_applicable` and reason `no_frontend_codebase` in the run manifest.
+2. For an applicable project, run the design-rule installer without overwriting project-local decisions or the project-context-owned index:
+
+```text
+devflow_design_rule(args=["--without-index"])
+```
+
+3. Verify these installed assets exist:
+   - `.context/spec/design/tokens/project-tokens.md`
+   - `.context/spec/design/recommendations/accessibility.md`
+   - `.context/spec/design/recommendations/component-library.md`
+   - `.context/spec/design/tools/ui-ux-pro-max/SKILL.md`
+4. Record `design_rule_pack.status: installed`, source `skill://workflow-design-rule-pack/assets/design/`, and the verified asset paths in `.planning/project-context-run.json`.
+5. Never use `--overwrite` during ordinary initialization. Existing confirmed project tokens and intentional local overrides take precedence. If an existing shared recommendation must be refreshed, require explicit user authorization and record it as a separate maintenance action.
+
+`--fast` only skips code-index generation. It does not skip this step for frontend projects.
+
+## Step 7 — Generate Context Spec Package
+
+Create `.context/spec/` after navigation files exist. Context specs are generated rule documents, not source-code indexes.
+
+### 7.1 Generate stack specs
+
+Use all Step 3d stack profiles, group by `stack_key`, and generate one `.context/spec/stacks/{stack_key}.md` per unique stack profile.
+
+Rules:
+- Deduplicate by `stack_key`, not by framework name alone.
+- If two codebases share the same framework but differ in major framework version or key libraries, generate separate stack specs.
+- Stack specs contain technology-stack guidance only. Do not include one codebase's local directory names, local naming habits, or route/module names as stack rules.
+- Stack specs must fill `## Per-Layer Rules` with stack-level guidance for every listed layer. Use `NOT_APPLICABLE` for layers that do not apply to the stack.
+- Each stack spec must include version metadata: generation date, source manifests, key dependency versions, dependency fingerprint, and regeneration triggers.
+
+### 7.2 Generate codebase specs
+
+For EACH frontend-type codebase, load `assets/codebase-frontend-spec-template.md` and write `.context/spec/frontend/{name}.md`.
+
+For EACH backend/service-type codebase, load `assets/codebase-backend-spec-template.md` and write `.context/spec/backend/{name}.md`.
+
+Codebase specs must:
+- Link to the matching stack spec by `stack_key`.
+- Separate `显式规则`, `代码推断`, and `待确认`.
+- Use navigation facts and actual scanned conventions; do not invent rules or promote inconsistent legacy code to a hard rule.
+- Include version metadata and regeneration triggers.
+
+### 7.3 Generate spec indexes
+
+Load `assets/context-spec-index-template.md` and write `.context/spec/index.md`.
+
+Load `assets/context-domain-index-template.md` and write:
+- `.context/spec/frontend/index.md`
+- `.context/spec/backend/index.md`
+- `.context/spec/design/index.md`
+
+For `.context/spec/design/index.md`, project-context is the only writer. When `design_rule_pack.status` is `installed`, add a `## Shared Design Rule Package` section that links to `tokens/`, `recommendations/`, and `tools/ui-ux-pro-max/`, preserves the priority order (confirmed project facts before recommendations), and identifies the pack as recommendations rather than project facts. When it is `not_applicable`, retain the explicit no-frontend reason.
+
+The root spec index must list:
+- Every stack spec with its `stack_key`.
+- Every codebase spec with codebase name, type, navigation file, and stack spec.
+- Read order for downstream skills:
+  1. `.planning/rules/INDEX.md`
+  2. `.context/spec/index.md`
+  3. matching `.context/spec/stacks/{stack_key}.md`
+  4. matching `.context/spec/frontend|backend/{codebase}.md`
+  5. matching `.context/spec/{domain}/index.md` and applicable depth specs
+  6. `.planning/navigation/{codebase}.md`
+  7. `.planning/code-index/` machine symbols/relations when present and source-level relation facts are needed
+  8. actual source files
+
+Each frontend/backend domain index must:
+
+- List every codebase-level spec in that domain.
+- Include a depth-spec registry row for every candidate topic and codebase.
+- Emit one exact machine marker per registry row:
+  - Present: `<!-- depth_spec: codebase={name}; domain={domain}; topic={topic}; status=present; path={output_path} -->`
+  - Not applicable: `<!-- depth_spec: codebase={name}; domain={domain}; topic={topic}; status=not_applicable; path=none -->`
+- Contain no marker from an earlier run that is absent from the current run manifest.
+
+### 7.4 Generate depth spec files (REQUIRED)
+
+本步骤**必须**执行。depth spec 是机器推导字段，刷新时必须与导航文件同步重新生成，禁止因为"已有旧文件"而跳过。
+
+Depth specs are topic-specific expansions of the codebase spec. Determine the topic list dynamically from navigation scan data, then load and fill the matching template from `assets/spec-templates/{codebase-type}/`. Do not iterate a hardcoded file list.
+
+**Backend topic discovery** (from backend-type codebase navigation):
+
+| Topic | Match rule | Conditional |
+|-------|-----------|-------------|
+| `service` | directory matching `**/service*/` or `**/svc/` | always when present |
+| `router` | directory matching `**/router*/`, `**/route*/`, `**/handler*/`, `**/controller*/`, `**/web/`, or route registration files | always when present |
+| `schema` | directory matching `**/schema*/`, `**/dto*/`, `**/vo*/`, `**/request*/`, `**/response*/`, or request/response type files | always when present |
+| `model` | directory matching `**/model*/`, `**/entity*/`, `**/domain/`, or ORM/entity files | always when present |
+| `repository` | directory matching `**/repository*/`, `**/repo*/`, `**/dao/`, or persistence adapter files | always when present |
+| `engine` | directory matching `**/engine*/`, `**/client*/`, `**/integration*/`, `**/external*/`, or outbound integration files | always when present |
+| `scheduler` | files or directories matching `**/cron*`, `**/job*`, `**/task*`, `**/scheduler*`, or framework scheduler annotations/registrations | presence of cron/job files |
+| `locator` | locator module detected | presence of locator-specific code |
+| `testing` | directory matching `**/test*/`, `**/tests/`, or files matching `**/*_test.*`, `**/test_*`, `**/*.spec.*` | always when present |
+| `directory-structure` | always | always |
+| `errors` | always | always — derived from HTTP exception and error mapping patterns |
+
+**Frontend topic discovery** (from frontend-type codebase navigation):
+
+| Navigation signal | Depth spec topic | Conditional |
+|---|---|---|
+| Router config, `app/`, `pages/`, `src/app/`, `src/pages/`, or framework file-based routes detected | `routing` | always when present |
+| API client dir/file exists (`**/api*/`, `**/client*/`, `**/request*`, `**/services*`) | `api-client` | always when present |
+| State management (store/redux/zustand/pinia/vuex/context/composable state) detected | `state` | always when present |
+| Components directory exists (`**/components/`, `**/ui/`, `**/widgets/`) | `components` | always when present |
+| Form patterns detected | `forms` | always when present |
+| Domain-specific editor detected | `case-editor` | presence of editor modules |
+| Test dir/file exists (`**/test*/`, `**/*.test.*`, `**/*.spec.*`) | `testing` | always when present |
+| always | `directory-structure` | always |
+
+**Generation rules:**
+
+Build `candidate_topics` and `expected_topics` independently for every local/scannable codebase:
+
+1. Enumerate `candidate_topics` from the current filenames in `assets/spec-templates/{backend|frontend}/`; do not copy a fixed count or list into a completion gate.
+2. Apply the discovery table to the navigation evidence. The matching subset becomes `expected_topics`.
+3. Record both sets in `.planning/project-context-run.json.topic_inventory`.
+
+The runtime inventory is the single source for generation and validation. A candidate topic must appear exactly once as either generated or `NOT_APPLICABLE`.
+
+Choose output paths without collisions:
+
+- When a domain has one codebase: `.context/spec/{domain}/{topic}.md`
+- When a domain has multiple codebases: `.context/spec/{domain}/{codebase}/{topic}.md`
+
+For each expected topic:
+
+1. Record the codebase's absolute or project-relative root as `codebase_root`.
+2. Collect every source file actually used to derive the topic as `source_paths` relative to that codebase root. Do not use directories or generated spec files as substitutes.
+3. Compute `source_fingerprint` with the same algorithm as `scripts/validate_initialization.py`: sort unique paths, hash each file, then hash the sequence of `relative_path + NUL + file_sha256 + newline`.
+4. Load `assets/spec-templates/{backend|frontend}/{topic}.md`, fill placeholders from navigation facts and stack template, and write the selected output path.
+5. Add one matching entry to `.planning/project-context-run.json.depth_specs`.
+6. Record every undiscovered candidate topic in `not_applicable_topics` and in the matching domain spec index.
+7. Emit the exact matching `depth_spec` machine marker in the domain index.
+
+Each depth spec uses the same structure: Generation Metadata, Scope, Source Summary (Type+Confidence), Stack-Specific Conventions, Observed Patterns, Rules (Strength+Source+Notes), Current Project Shape, Not Applicable, Pending Confirmation.
+
+Placeholder filling rules:
+- `{{run_id}}`: the current invocation's immutable run ID.
+- `{{generated_at}}`: ISO-8601 UTC time when this file was regenerated.
+- `{{source_fingerprint}}`: fingerprint computed from this manifest entry's `source_paths`.
+- `{{scope_path}}`: derived from codebase root + navigation scan.
+- `{{source_summary}}`: rows from navigation scan (`代码推断 | OBSERVED | high`), stack template (`SHOULD | medium`), and rule files (`MUST | high`).
+- `{{stack_layer_rules}}`: extract the matching subsection from `.context/spec/stacks/{stack_key}.md` → `## Per-Layer Rules`. If the subsection is `NOT_APPLICABLE`, record that in this field and in `{{not_applicable}}`.
+- `{{observed_rules}}`: rows or bullets from navigation facts, call-chain tracing, codebase conventions, explicit rule files, and lessons. Do not mix in generic stack rules here.
+- `{{rules_table}}`: merged rows from stack layer rules, observed project conventions, explicit rule files, and lessons. Each row is `\| {{rule}} | {{strength}} | {{source}} | {{notes}} |`.
+- `{{current_shape}}` / `{{directory_tree}}`: from navigation directory map and call chain map.
+- `{{not_applicable}}`: layers and patterns observed to be absent.
+- `{{pending}}`: items not yet confirmed.
+
+Topics not discovered are skipped. Record them in the domain index and run manifest as `NOT_APPLICABLE`. A skipped topic must not be added to `depth_specs`.
+
+If a topic is discovered but the matching template file is missing, do not silently skip it. Record a `PENDING_TEMPLATE` blocker in `.planning/STATE.md` front matter and in the matching domain spec index:
+
+```yaml
+blockers:
+  - type: PENDING_TEMPLATE
+    codebase: {{name}}
+    topic: {{topic}}
+    reason: found {{matched_path}} but no template in assets/spec-templates/{{backend_or_frontend}}/{{topic}}.md
+    impact: depth spec not generated for this layer
+```
+
+For the domain spec index, include the same topic, matched path, missing template path, and impact under `## Pending Confirmation`.
+
+Do not mark initialization fully complete while `PENDING_TEMPLATE` blockers exist.
+
+**Completion gate:**
+
+- Every frontend/backend codebase has its codebase-level spec.
+- Every present domain has its domain index.
+- Every domain index contains the current run ID and exactly the machine markers represented by the run manifest.
+- Every `(codebase, domain, topic)` in `expected_topics` has exactly one run-manifest entry and one output file.
+- Every undiscovered candidate topic is recorded as `NOT_APPLICABLE`, not generated to satisfy a fixed count.
+- No two manifest entries share one output path.
+- Every depth spec contains the current `run_id` and matching `source_fingerprint`.
+
+Any mismatch means Step 7.4 is incomplete.
+
+## Step 8 — Generate Rule Package Files
+
+Create the project rule package that downstream skills (`workflow-frontend-tech-spec`, `workflow-backend-tech-spec`) check first in their discovery order. This step consolidates information already collected during structure scan and generated context specs — it does not invent new rules.
+
+### 8.1 Create `.planning/rules/` directory
+
+```bash
+mkdir -p .planning/rules
+```
+
+### 8.2 Generate `.planning/execution-contract.md`
+
+Load `assets/execution-contract-template.md` and fill from scan results:
+
+- **Backend layer models**: from each backend-type codebase navigation file's "Layer Conventions" table. Map handler/service/repository/DAO directories and describe the dependency direction. One subsection per backend codebase.
+- **Conversion rules**: from `.cursorrules` (if present) or codebase navigation Notes. Capture domain↔vo↔model conversion rules verbatim.
+- **Interface rules**: from `.cursorrules` or code scan. E.g., "handler implements handler interface with RegisterRoutes method".
+- **Frontend component hierarchies**: from each frontend-type codebase navigation file's "Component Conventions" table. Map pages→page components→common components→layout→hooks. One subsection per frontend codebase.
+- **TDD Strategy**: already embedded in template default. Fill from codebase conventions when the project has explicit TDD rules. Keep the template default otherwise.
+- **Code Generation**: `待确认` unless codegen commands (wire, protobuf, swagger, etc.) were found during scan. If found, list each command with its source and run condition.
+- **Verification Gates**: already embedded in template default. Fill additional project-specific verification rules from codebase conventions when present. Keep the template default otherwise.
+
+Rules:
+- Only write what was observed during scan. Do not invent layer rules or component conventions.
+- If `.cursorrules` or `AGENTS.md` / `CLAUDE.md` contain explicit conventions, quote or summarize them in the relevant section.
+- Mark unobserved sections as `待确认`, not with guessed defaults.
+
+### 8.3 Generate `.planning/toolchain.md`
+
+Load `assets/toolchain-template.md` and fill from the "Commands" tables in all codebase navigation files:
+
+- Consolidate commands from each codebase, grouped by codebase name.
+- If database migration commands were found during scan, add them.
+- If code generation commands (wire, protobuf, swagger, etc.) were found, add them.
+- If a command is `待确认` in the navigation files, keep it as `待确认` here.
+
+### 8.4 Generate `.planning/rules/INDEX.md`
+
+Load `assets/rules-index-template.md` and fill status for every rule source:
+
+- Files created in Step 8 (`execution-contract.md`, `toolchain.md`) → status `present`.
+- Files created in Step 7 (`.context/spec/index.md`, stack specs, frontend/backend/design indexes, codebase specs) → status `present`.
+- Files found during Step 3 scan (`.cursorrules`, `AGENTS.md`, existing `.context/spec/`, etc.) → status `present` with path.
+- Files not found → status `missing`.
+- Files that don't apply (e.g., frontend rules for backend-only projects) → status `不适用`.
+
+This file is the first thing downstream skills read. It must accurately reflect what exists after initialization.
+
+## Step 9 — Generate STATE.md
+
+Load `assets/state-template.md` and create `.planning/STATE.md` with:
+
+- Initialization date
+- Current step
+- Completed steps
+- Pending steps
+- Each codebase: name, type, path, scan status, navigation file path, stack_key, and generated spec path
+- Whether `.planning/PROJECT.md` exists
+- Whether `.planning/navigation/` exists
+- Whether `.context/spec/` exists and each required spec file is complete
+- Whether each codebase navigation is complete
+- Whether `.planning/rules/INDEX.md`, `.planning/execution-contract.md`, and `.planning/toolchain.md` exist
+- Current `run_id`, `run_started_at`, and `code_index_status`
+- Design rule pack status and reason
+- Last scan timestamp
+- Blockers
+- Known missing information
+- Recommended next step, usually `workflow-requirement-baseline` after the user provides a requirement
+
+## Step 9.5 — Finalize Run Manifest
+
+Load `assets/run-manifest-template.json` and write `.planning/project-context-run.json`.
+
+Requirements:
+
+- `run_id` and `started_at` exactly match the values captured before Step 1.
+- `mode` is `full` or `fast`.
+- `code_index_status` is `complete` in full mode and `skipped` in fast mode.
+- `code_index_skip_reason` is `none` in full mode or the explicit skip flag in fast mode.
+- `design_rule_pack` has status `installed` with its verified assets for frontend projects, or `not_applicable` with a reason for projects without frontend codebases.
+- Every local/scannable frontend/backend codebase has one `topic_inventory` entry. Its `candidate_topics` come from current template filenames and its `discovered_topics` come from the Step 7.4 evidence match.
+- Every expected depth topic has one entry with its codebase root, actual output path, complete codebase-relative `source_paths`, and computed `source_fingerprint`.
+- Every undiscovered candidate topic is listed under `not_applicable_topics`.
+- JSON placeholders and example rows are fully removed.
+
+## Step 10 — Review Gate
+
+This is the final step. Before finishing, review generated files against `references/navigation-guide.md`, then run the deterministic completion validator.
+
+Check:
+
+- All codebase locations from Step 1 are recorded in INDEX.md Codebase Registry.
+- Each codebase has a navigation file at `.planning/navigation/{name}.md`.
+- Frameworks are recorded or marked `待确认` for each codebase.
+- Entry points and key directories are recorded or marked `待确认` for each codebase.
+- Each codebase has a Directory Map (3a gate: all top-level/second-level directories listed).
+- Each codebase has a Call Chain Map (3b gate: all handlers/routes traced).
+- Each codebase has Conventions (3c gate: at minimum layer order or component hierarchy recorded).
+- Each local/scannable codebase has a Stack Profile (3d gate: stack_key, manifest path, and dependency fingerprint recorded).
+- Every detected stack profile has `.context/spec/stacks/{stack_key}.md`.
+- Every frontend-type codebase has `.context/spec/frontend/{name}.md`.
+- Every backend/service-type codebase has `.context/spec/backend/{name}.md`.
+- Every depth topic discovered in Step 7.4 has exactly one output and manifest entry.
+- Every topic not discovered in Step 7.4 is recorded as `NOT_APPLICABLE`; no fixed topic count is imposed.
+- Every frontend/backend domain index has exactly the current manifest's depth-spec registry markers and no stale markers.
+- `.context/spec/index.md` lists every stack spec and codebase spec mapping.
+- All generated context specs include generation metadata and regeneration triggers; depth specs include the current run ID and source fingerprint.
+- Frontend-type codebases have Route-Component Map and Data Flow tables.
+- Backend-type codebases have API Modules, Scheduled Jobs, and External Integrations tables.
+- Commands are recorded or marked `待确认` for each codebase.
+- `.planning/execution-contract.md` exists and contains layer order and component hierarchy from scan results, not invented defaults.
+- `.planning/toolchain.md` exists and consolidates commands from all codebase navigation files.
+- `.planning/rules/INDEX.md` exists and accurately reflects generated `.context/spec/` files as present.
+- Project rule package locations are recorded when present, including `.context/spec/`, `.context/workflow/`, and lessons.
+- History model locations are recorded, and outbound-call style `features/` history is labeled as optional legacy rather than the default source.
+- `.planning/PROJECT.md` links to `.planning/navigation/INDEX.md`.
+- `.planning/navigation/INDEX.md` Codebase Registry links to every codebase navigation file.
+- `.planning/navigation/INDEX.md` includes downstream read contract.
+- `.planning/navigation/INDEX.md` and `.context/spec/index.md` describe `.planning/code-index/` as the machine fact layer before source reads, unless fast mode skipped generation.
+- Every frontend project has the design rule assets from Step 6.6, while `.context/spec/design/index.md` remains generated by project-context rather than overwritten by the installer.
+- Future output locations include `.planning/features/{功能名}/功能点梳理.md`.
+- No requirements or roadmap were generated without explicit user request.
+- `STATE.md` includes completion statuses and next action for each codebase.
+- Generated files include an initialization quality summary.
+
+Run:
+
+```text
+devflow_skill_script(script="project-context-validate", args=["--root", ".", "--manifest", ".planning/project-context-run.json"])
+```
+
+The validator checks current-run markers, full-mode code-index freshness, fast-mode skip evidence, template-derived topic inventory partitioning, dynamic depth-spec outputs, domain-index registry markers, source fingerprints, duplicate identities, and output-path collisions.
+
+Fix every reported gap and rerun the validator. If the command does not pass, initialization is incomplete and the final response must report the blocker instead of claiming success.
+
+Quality status rules:
+
+- `complete`: required fields are known and commands are identified.
+- `partial`: project is local and scannable, but some required fields are `待确认`.
+- `pending`: project location is remote/unavailable or scan could not run.
+- `not_applicable`: this codebase type does not support this field (e.g., component conventions for a backend service).
+
+## Downstream Read Contract
+
+This skill writes the contract and the initial rule package. Other skills consume them:
+
+- Requirement discussion should read `.planning/PROJECT.md`, `.planning/navigation/INDEX.md`, and `.planning/rules/INDEX.md`.
+- Feature breakdown should read `.planning/PROJECT.md`, `.planning/navigation/INDEX.md`, and relevant codebase navigation files as needed.
+- Test guide generation should read `.planning/PROJECT.md`, `.planning/navigation/INDEX.md`, and `.planning/rules/INDEX.md`.
+- Frontend technical planning should read `.planning/rules/INDEX.md` → `.context/spec/index.md` → matching `.context/spec/stacks/{stack_key}.md` → matching `.context/spec/frontend/{codebase}.md` → `.context/spec/frontend/index.md` and applicable depth specs → `.planning/navigation/{codebase}.md` → `.planning/code-index/` when relation facts are needed → actual source files.
+- Backend technical planning should read `.planning/rules/INDEX.md` → `.context/spec/index.md` → matching `.context/spec/stacks/{stack_key}.md` → matching `.context/spec/backend/{codebase}.md` → `.context/spec/backend/index.md` and applicable depth specs → `.planning/navigation/{codebase}.md` → `.planning/code-index/` when relation facts are needed → actual source files.
+- Change-list generation should use `.planning/navigation/INDEX.md` for output locations and project conventions, and use discovered `.context/spec/` + `.planning/rules/` sources for task-level gates.