prizmkit 1.1.8 → 1.1.10

package/bundled/skills/prizmkit-deploy/SKILL.md

@@ -1,73 +1,76 @@
 ---
 name: "prizmkit-deploy"
-description: "Generate or update DEPLOY.md with local dev setup, testing, production deployment, and rollback procedures. Fully autonomous. Use after /prizmkit-retrospective, before /prizmkit-committer. Trigger on: 'deploy docs', 'deployment guide', 'how to deploy', 'DEPLOY.md'. (project)"
+description: "Generate or update .prizmkit/deploy.md with local dev setup, testing, production deployment, and rollback procedures. On-demand skill — trigger when deployment docs are needed. Trigger on: 'deploy docs', 'deployment guide', 'how to deploy', 'deploy.md'. (project)"
 ---
 
 # PrizmKit Deploy
 
 ### When to Use
-- After `/prizmkit-retrospective` and before `/prizmkit-committer` to complete documentation before commit
-- After a batch of features has been implemented and reviewed
 - When the project has no deployment documentation yet
 - When new infrastructure components have been added (new database, cache, message queue, etc.)
+- When deployment-related configuration has changed significantly
+- When explicitly requested by user or caller
 
 ### When NOT to Use
-- Mid-feature development (deployment docs should reflect reviewed, stable code)
-- For actual deployment execution (this skill only produces docs)
-- Fast-path bug fixes (no deployment doc update needed)
+- For actual deployment execution (this skill only produces documentation)
+- When only application logic changed with no infra/config impact
 
-### Pipeline Safety
-- **Fully autonomous** — no user interaction required at any step
+> **On-demand skill** — not part of the default `plan → implement → code-review → retrospective → committer` chain. Invoke independently when deployment documentation needs creation or update.
+
+### PRECONDITION
+- Project contains deployable artifacts (at least one of: `package.json`, `Dockerfile`, `Makefile`, `go.mod`, `Cargo.toml`, `pyproject.toml`, or equivalent)
+
+## Context Loading
+
+1. **Architecture context**: Read `.prizm-docs/root.prizm` → identify modules with deployment-relevant components (APIs, services, workers)
+2. **Project config**: Read `.prizmkit/config.json` for `deploy_strategy` and `tech_stack`
+   - If `.prizmkit/config.json` does not exist → proceed without it, infer from project file scanning. Log warning: "No .prizmkit/config.json found — inferring deployment strategy from project files."
+3. **Module detail**: Read relevant `.prizm-docs/<module>.prizm` L1/L2 for INTERFACES and DEPENDENCIES sections that inform deployment topology
 
 ## Execution Steps
 
-**Phase 1 — Context Gathering:**
-1. Read `.prizmkit/config.json`:
-   - `deploy_strategy` — user's confirmed deployment approach (may be absent)
-   - `tech_stack` — detected or user-provided technology stack
-   - **If `.prizmkit/config.json` does not exist**: proceed without it — infer deployment approach entirely from project file scanning in steps 2-3. Log a warning: "No .prizmkit/config.json found — inferring deployment strategy from project files. Run `/prizmkit-init` to generate config."
-2. Scan project for deployment-related files:
+**Phase 1 — Project Scanning:**
+1. Scan project for deployment-related files:
    - Container: `Dockerfile`, `docker-compose.yml`, `.dockerignore`
    - Cloud platforms: `vercel.json`, `netlify.toml`, `fly.toml`, `app.yaml` (GCP), `appspec.yml` (AWS)
    - CI/CD: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `bitbucket-pipelines.yml`
    - Package managers: `package.json` scripts (start, build, preview), `Makefile`, `Procfile`
    - Infrastructure as Code: `terraform/`, `pulumi/`, `cdk/`, `serverless.yml`
-3. Scan source code for environment variable references:
+2. Scan source code for environment variable references:
    - Grep for `process.env.`, `os.environ`, `os.Getenv`, `env::var`, `System.getenv`
    - Cross-reference with `.env.example`, `.env.template`, or `.env.sample` if they exist
    - Catalog all env vars with their usage context
-4. Check for existing `DEPLOY.md` (or `docs/deployment.md`, `docs/DEPLOY.md`)
-5. Read recent git log to identify newly added infrastructure components since last deploy doc update:
-   - If `DEPLOY.md` exists → use `git log -1 --format=%H -- DEPLOY.md` to find the last commit that touched it, then `git diff <that-commit>..HEAD` to identify new infra files
-   - If `DEPLOY.md` does not exist → treat all infrastructure as "new"
+3. Check for existing `.prizmkit/deploy.md`
+4. If `.prizmkit/deploy.md` exists → use `git log` to identify infra changes since last update; otherwise treat all infrastructure as "new"
 
 **Phase 2 — Document Generation:**
-6. If NO existing deploy doc:
-   - Generate full `DEPLOY.md` from template (`${SKILL_DIR}/assets/deploy-template.md`)
+5. If NO existing deploy doc:
+   - Generate `.prizmkit/deploy.md` from template (`${SKILL_DIR}/assets/deploy-template.md`)
    - Fill all sections based on scanned project state
    - If `deploy_strategy` exists in config → use it as the authoritative deployment approach
-   - If `deploy_strategy` is absent → infer from detected files (Dockerfile → Docker-based, vercel.json → Vercel, etc.) and note "Inferred from project files — confirm with `/prizmkit-plan` on next feature"
-7. If existing deploy doc found:
+   - If `deploy_strategy` is absent → infer from detected files (Dockerfile → Docker-based, vercel.json → Vercel, etc.) and note "Inferred from project files"
+6. If existing deploy doc found:
    - Compare current project state against documented state
    - Identify gaps: new env vars not documented, new services not covered, outdated commands
    - Apply incremental updates — preserve user-written sections, only add/update auto-detectable content
    - Mark updated sections with `<!-- Updated by prizmkit-deploy -->` comment
 
 **Phase 3 — Validation:**
-8. Verify completeness checklist:
+7. Verify completeness checklist:
    - [ ] All detected env vars are documented with descriptions
    - [ ] Local development setup commands are runnable (check referenced scripts/commands exist)
    - [ ] Build command documented and exists in package.json/Makefile
-   - [ ] Production deployment steps match `deploy_strategy` in config
+   - [ ] Production deployment steps match `deploy_strategy` in config (if configured)
    - [ ] Health check or verification step is included
-9. If any checklist item fails, add a `## TODO` section at the bottom listing what needs manual completion
-10. Output: `DEPLOY.md` path, summary of sections generated/updated, list of TODOs if any
+8. If any checklist item fails, add a `## TODO` section at the bottom listing what needs manual completion
+9. If interactive session is available → show summary and ask if user wants to review before finishing
+10. Output: `.prizmkit/deploy.md` path, summary of sections generated/updated, list of TODOs if any
 
-**HANDOFF:** `/prizmkit-committer` — commit all changes including the updated `DEPLOY.md`.
+**HANDOFF:** `/prizmkit-committer` — commit changes including `.prizmkit/deploy.md`.
 
 ## Document Sections
 
-The generated `DEPLOY.md` includes these sections (skip any that don't apply to the project):
+The generated deploy doc includes these sections (skip any that don't apply to the project):
 
 | Section | Content | Source |
 |---------|---------|--------|
@@ -84,7 +87,7 @@ The generated `DEPLOY.md` includes these sections (skip any that don't apply to
 
 ## Incremental Update Rules
 
-When updating an existing `DEPLOY.md`:
+When updating an existing `.prizmkit/deploy.md`:
 - **NEVER delete** user-written content (sections without `<!-- Updated by prizmkit-deploy -->` markers)
 - **ADD** newly detected env vars to the Environment Variables table
 - **ADD** new services/components to Production Deployment
@@ -99,7 +102,7 @@ When updating an existing `DEPLOY.md`:
 - Project has `Dockerfile`, `docker-compose.yml`, `package.json` with build script
 - 12 env vars detected in source code, `.env.example` has 8
 
-**Output:** `DEPLOY.md` with all sections filled, plus TODO:
+**Output:** `.prizmkit/deploy.md` with all sections filled, plus TODO:
 ```
 ## TODO
 - [ ] 4 environment variables found in code but missing from `.env.example`: `REDIS_URL`, `SMTP_HOST`, `SMTP_PORT`, `SENTRY_DSN`

package/bundled/skills/prizmkit-deploy/assets/deploy-template.md

@@ -1,5 +1,5 @@
 # Deployment Guide: [PROJECT_NAME]
-<!-- Replace [PROJECT_NAME] with: project_name from feature-list.json, or name from package.json, or the project root directory name (in that priority order) -->
+<!-- Replace [PROJECT_NAME] with: name from package.json, or the project root directory name -->
 
 > Generated by PrizmKit Deploy
 

package/bundled/skills/prizmkit-implement/SKILL.md

@@ -1,87 +1,55 @@
 ---
 name: "prizmkit-implement"
-description: "Execute plan.md tasks with TDD approach. Respects task ordering and dependencies. Use after /prizmkit-plan (or /prizmkit-analyze). Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
+description: "Execute plan.md tasks with TDD approach. Respects task ordering and dependencies. Use after /prizmkit-plan. Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
 ---
 
 # PrizmKit Implement
 
 ### When to Use
-- After `/prizmkit-plan` (or `/prizmkit-analyze`) when ready to write code
+- After `/prizmkit-plan` when ready to write code
 - User says "implement", "build", "code it", "start coding", "develop"
 - For fast-path: user describes a simple change directly (fast-path skips specify, but still requires a simplified plan.md with Tasks section)
 
 **PRECONDITION:**
 
-| Mode | Required Artifact | Directory | Check | If Missing |
-|---|---|---|---|---|
-| **Feature** (default) | `plan.md` with Tasks section | `.prizmkit/specs/###-feature-name/` | File exists + unchecked tasks | Run `/prizmkit-plan` |
-| **Refactor** | `plan.md` with Tasks section | `.prizmkit/refactor/<refactor-slug>/` | File exists + unchecked tasks | Run `/prizmkit-plan` in refactor mode |
-| **Bugfix** | `plan.md` with Tasks section | `.prizmkit/bugfix/<BUG_ID>/` | File exists + unchecked tasks | Run `/prizmkit-plan` in bugfix mode |
-
-**Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
-
-## Execution Steps
-
-1. **Detect mode and read context**:
-   - Locate `plan.md` (check the artifact directory passed by the calling workflow, or auto-detect per PRECONDITION above)
-   - Read `plan.md` (including Tasks section)
-   - Read the companion input document for full context:
-     - **Feature mode**: read `spec.md` in the same directory
-     - **Refactor mode**: read `refactor-analysis.md` in the same directory — pay special attention to Scope Boundary (do not implement changes outside scope) and Baseline Tests (all must still pass)
-     - **Bugfix mode**: read `fix-plan.md` in the same directory
-2. Load project context — use the most efficient source available (check in this order):
-   - If `context-snapshot.md` exists in the feature directory → read it. Section 3 has Prizm docs + TRAPS. Section 4 has File Manifest (Tier-2/3) or full source (Tier-1). Read source files on-demand as directed by the manifest.
-   - Else if `session-summary.md` exists in the feature directory → read it for quick context recovery (completed tasks, key decisions, active TRAPS). Then load only the L1/L2 docs for modules listed in "Files Changed" — skip unrelated modules.
-   - Otherwise → **self-service context fallback**:
-     1. Read **architecture index**: `.prizm-docs/root.prizm` and relevant L1/L2 for affected modules. Pay special attention to TRAPS and DECISIONS.
-     2. Scan needed source files
-3. Check if checkpoint tasks are complete before proceeding to next phase
-4. For each unchecked task in order:
-   a. If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group
-   b. Read L2 doc for target file's module. TRAPS save you from repeating known mistakes.
-      - If L2 exists: check TRAPS and DECISIONS before modifying files.
-      - If L2 does not exist and this task creates a new module directory or adds significant source files: create L2 using the L2 GENERATION TEMPLATE (see PRIZM-SPEC). Seed KEY_FILES and DEPENDENCIES from the files being created. TRAPS and DECISIONS can be minimal initially — `/prizmkit-retrospective` will enrich them.
-      - Judgment call: not every directory needs L2. Create L2 when the module has meaningful logic, non-obvious coupling, or design decisions worth preserving. Skip for trivial wrapper directories or single-config modules.
-   c. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
-   d. Mark task as `[x]` in `plan.md` Tasks section immediately — not batched at the end. Immediate marking means the plan always reflects true progress, even if the session is interrupted.
-   e. After all tasks, append '## Implementation Log' to `context-snapshot.md` (if running in pipeline context): files changed/created, key decisions, notable discoveries.
-   f. Error handling: sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
-5. At each checkpoint: verify build passes and tests pass. Checkpoints catch integration errors early — skipping them means cascading failures in later phases that are much harder to debug.
-6. After all tasks: run full test suite
-7. **Deploy guide update** — only when dependency manifests (package.json, requirements.txt, etc.) changed during this task.
-      → Read `${SKILL_DIR}/references/deploy-guide-protocol.md` and follow its protocol.
-8. Output implementation summary with pass/fail status
-
-## Task Format in plan.md
-
-Tasks in plan.md look like this:
-```markdown
-## Tasks
-
-### Phase 1: Data Layer
-- [ ] Create User model with avatar field in src/models/user.ts
-- [ ] Add S3 upload utility in src/lib/s3.ts
-- [x] ~~Set up database migration~~ (already done)
-
-### Phase 2: API [P]
-- [ ] [P] POST /api/avatar endpoint in src/routes/avatar.ts
-- [ ] [P] DELETE /api/avatar endpoint in src/routes/avatar.ts
-
-### Phase 3: UI
-- [ ] Avatar upload component in src/components/AvatarUpload.tsx
-- [ ] CP: Integration checkpoint — full test suite must pass
-```
-
-- `[ ]` / `[x]` — unchecked / completed
-- `[P]` — can run in parallel with other `[P]` tasks in the same phase
-- `CP:` — checkpoint where build + tests must pass before continuing
+| Required Artifact | Check | If Missing |
+|---|---|---|
+| `plan.md` with Tasks section | File exists + unchecked tasks | Run `/prizmkit-plan` |
+| `spec.md` | File exists in same directory as plan.md | Run `/prizmkit-plan` |
+
+**Artifact directory**: Accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `artifact_dir` | No | Directory containing spec.md + plan.md. If omitted, auto-detect per precondition above. |
+
+## Context Loading
+
+Before implementation, load context once:
+
+1. **Task context**: Read `plan.md` (including Tasks section) and `spec.md` from the artifact directory. If other companion documents exist in the directory (e.g., `refactor-analysis.md`), read them for additional context.
+2. **Architecture context**: Read `.prizm-docs/root.prizm` (L0 — project overview, module index, tech stack, conventions) and relevant L1/L2 docs for affected modules. Pay special attention to TRAPS (known pitfalls) and DECISIONS (architectural choices).
+
+> `.prizm-docs/` uses a 3-level hierarchy: L0 (`root.prizm`) is the project-wide index. L1 (e.g., `auth.prizm`) covers a module — its key files, interfaces, dependencies, traps, and decisions. L2 is for sub-modules with their own complexity. Implement reads these docs to avoid repeating known mistakes; `/prizmkit-retrospective` is responsible for updating them after implementation.
+
+## Execution
+
+For each unchecked task in plan.md, in order:
+
+1. Read L1/L2 doc for the target file's module — check TRAPS and DECISIONS before modifying files
+2. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
+3. Mark task as `[x]` in `plan.md` immediately after completion — not batched at the end. Immediate marking means plan.md always reflects true progress, even if the session is interrupted.
+4. **Parallel tasks**: If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group. Sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
+5. **Checkpoint tasks** (`CP:` prefix in plan.md): When a checkpoint task is reached, verify build passes and tests pass before continuing. Checkpoints catch integration errors early — skipping them means cascading failures in later phases.
+6. After all tasks complete: run full test suite.
 
 ## Recovery
 
 If a session is interrupted mid-implementation:
 - Completed tasks are already marked `[x]` in plan.md (because we mark immediately)
-- Resume by re-running `/prizmkit-implement` — it picks up from the first unchecked task
-- context-snapshot.md persists across sessions for consistent context
+- Resume by re-running `/prizmkit-implement` — it picks up from the first unchecked `[ ]` task
 
 **HANDOFF:** `/prizmkit-code-review`
 
@@ -89,5 +57,4 @@ If a session is interrupted mid-implementation:
 
 - Code files created/modified as specified in plan.md Tasks section
 - `plan.md` Tasks section updated with completion markers `[x]`
-- `DEPLOY.md` created/updated (only when new frameworks/tools were added)
 - Implementation summary output to conversation

package/bundled/skills/prizmkit-init/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: "prizmkit-init"
-description: "Project takeover and bootstrap. Scans any project, generates Prizm docs, configures hooks. Use this skill whenever a user opens a new project for the first time, says 'initialize', 'set up PrizmKit', 'take over this project', 'bootstrap', 'scan this codebase', 'init', or when .prizm-docs/ doesn't exist yet. Also use when PrizmKit was just installed via npx but not yet initialized. (project)"
+description: "Project takeover and bootstrap. Scans any project, generates Prizm docs and project brief. Use this skill whenever a user opens a new project for the first time, says 'initialize', 'set up PrizmKit', 'take over this project', 'bootstrap', 'scan this codebase', 'init', or when .prizm-docs/ doesn't exist yet. Also use when PrizmKit was just installed via npx but not yet initialized. (project)"
 ---
 
 # PrizmKit Init
 
-Project takeover and bootstrap skill. Scans any project (brownfield or greenfield), generates Prizm documentation, and configures platform-specific hooks for documentation sync. Supports CodeBuddy, Claude Code, and dual-platform installations.
+Project takeover and bootstrap skill. Scans any project (brownfield or greenfield), generates Prizm documentation and project brief. Supports CodeBuddy, Claude Code, and dual-platform installations.
 
 ### When to Use
 - Taking over a new project (brownfield or greenfield)
@@ -14,35 +14,58 @@ Project takeover and bootstrap skill. Scans any project (brownfield or greenfiel
 - After `npx prizmkit install` when project has no `.prizm-docs/`
 
 ### When NOT to Use
-- `.prizm-docs/` already exists and is up to date → use `/prizmkit-prizm-docs` (Update) instead
-- User just wants to update stale docs → use `/prizmkit-prizm-docs` (Update or Rebuild)
-- User wants to start a feature → skip init if already initialized, go to `/prizmkit-plan`
+- All artifacts exist and are up to date → use `/prizmkit-prizm-docs` (Update) instead if you only want to resync docs
+- User just wants to update stale docs → use `/prizmkit-prizm-docs` (Update or Rebuild) instead (faster, targeted)
+- User wants to start a feature on an already-initialized project → skip init, go to `/prizmkit-plan`
 
 ### Error Handling
-- If `.prizm-docs/` already exists: ask user if they want to reinitialize (overwrites) or update (preserves)
+- If artifacts already exist: idempotent status check offers regenerate/skip choices (see Phase 3: Idempotent Status Check)
 - If no source files found in any directory: fall back to greenfield mode
-- If platform cannot be detected: ask user explicitly which platform(s) to configure
 
 ## Execution Steps
 
-**PLATFORM DETECTION (before anything else):**
-1. Check for platform indicators in the current environment:
-   - CodeBuddy: `.codebuddy/` directory exists, or running inside `cbc` session
-   - Claude Code: `.claude/` directory exists, or running inside `claude` session
-   - Both: Both directories exist
-   - Unknown: Neither exists — ask the user which platform(s) to configure
-2. Store detected platform in `.prizmkit/config.json` as `"platform": "codebuddy" | "claude" | "both"`
-
-MODE DETECTION:
-- If `.prizm-docs/` exists: Ask user if they want to reinitialize or update
-  - **Reinitialize**: overwrites `.prizm-docs/` and `config.json` tech_stack (fresh start)
-  - **Update**: re-scans tech stack and merges changes into existing `config.json` (see Step 3b merge strategy); updates `root.prizm` TECH_STACK if changed; preserves existing `.prizm-docs/` L1/L2 docs; checks for missing L1/L2 docs and creates them for modules with source files (see Update Supplement below)
+**Phase 1: Platform Detection**
+1. Detect which platform is running (CodeBuddy or Claude Code) via AI CLI environment.
+2. Hold detected platform value in memory — written to disk in Phase 6 along with other config fields.
+
+**Phase 2: Mode Detection**
 - If project has source code: brownfield mode
 - If project is nearly empty: greenfield mode
 
+**Phase 3: Idempotent Status Check**
+
+Scan all init artifacts and display their status:
+
+| Artifact | Path | Check |
+|----------|------|-------|
+| Prizm docs | `.prizm-docs/` | Directory exists + `root.prizm` present |
+| Runtime config | `.prizmkit/config.json` | File exists |
+| Project brief | `.prizmkit/plans/project-brief.md` | File exists |
+
+Display status table to user:
+```
+Init Status Check:
+  [exists]  .prizm-docs/          (N files)
+  [exists]  .prizmkit/config.json
+  [missing] .prizmkit/plans/project-brief.md
+```
+
+- **If all missing**: skip interaction, proceed to generate everything.
+- **If some exist**: ask user once:
+  - **[A] Regenerate all** — overwrite all existing artifacts (fresh start)
+  - **[B] Only generate missing** — skip existing, fill gaps (default)
+  - **[C] Pick per item** — ask for each existing artifact: regenerate or skip
+
+Each subsequent phase checks its artifact's action before executing:
+- `action == skip` → output "Skipped (exists)" and move on
+- `action == generate | regenerate` → run normally
+- **Special case for `.prizm-docs/`**:
+  - `skip` = **Update** mode: preserve existing L1/L2 docs, re-scan tech stack, merge changes, check for missing docs (see `${SKILL_DIR}/references/update-supplement.md`)
+  - `regenerate` = **Reinitialize**: overwrite everything
+
 BROWNFIELD WORKFLOW (existing project):
 
-**Step 1: Project Scanning**
+**Phase 4: Project Scanning**
 1. Detect tech stack from build files (`package.json`, `requirements.txt`, `go.mod`, `pom.xml`, `Cargo.toml`, etc.)
 2. Map directory structure using a TWO-TIER model — flat structures lose the nesting relationships that AI needs to navigate the codebase:
    - TOP-LEVEL modules: directories directly under project root that contain source files or sub-directories with source files (e.g. `src/`, `internal/`, `lib/`)
@@ -68,8 +91,8 @@ BROWNFIELD WORKFLOW (existing project):
 
    **IMPORTANT**: Not all projects have all fields. A pure backend API will have no `frontend_framework` or `frontend_styling`. A library may have no database. Only record what is actually detected — never generate empty or placeholder values.
 
-**Step 2: Prizm Documentation Generation**
-Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Step 1:
+**Phase 5: Prizm Documentation Generation**
+Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Phase 4:
   - Create `.prizm-docs/` directory structure mirroring the source tree (sub-module dirs become subdirectories under `.prizm-docs/<top-level>/`)
   - Generate `root.prizm` (L0) with project meta and MODULE_INDEX listing only top-level modules. If module count > 15, use MODULE_GROUPS format instead (group by functional domain).
   - For each module entry in MODULE_INDEX/MODULE_GROUPS, include keyword tags extracted from the module's source files — scan for: exported symbols, imported packages, domain terms in file/directory names. Format: `- module-name [tag1, tag2, tag3]: ...`. Tags help AI match user intent to relevant modules.
@@ -77,25 +100,53 @@ Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structu
   - Create `changelog.prizm`
   - Skip L2 (lazy generation) — L2 is generated on first file modification, saving tokens upfront
 
-**Step 3: PrizmKit Workspace Initialization**
-3a. Create `.prizmkit/` directory:
+**Phase 6: Workspace Initialization**
+6a. Create `.prizmkit/` directory structure (if missing):
   - `.prizmkit/config.json` (adoption_mode, speckit_hooks_enabled, platform)
   - `.prizmkit/specs/` (empty)
+  - `.prizmkit/plans/` (empty — needed by Phase 7 and future pipeline tasks)
 
-3b. Write detected tech stack to `.prizmkit/config.json`:
+6b. Write detected tech stack to `.prizmkit/config.json`:
    → Read `${SKILL_DIR}/references/config-schema.md` for merge strategy, field definitions, and examples.
 
-**Step 4: Hook & Settings Configuration**
-
-4a. Read or create platform settings file (`.codebuddy/settings.json` or `.claude/settings.json`)
-4b. Add UserPromptSubmit and PostToolUse hooks for automatic prizm-docs reminders
-4c. For Claude Code: also add `permissions` entries and `.claude/rules/` for documentation enforcement:
-  - `.claude/rules/prizm-documentation.md` (glob-scoped source file rules)
-  - `.claude/rules/prizm-commit-workflow.md` (commit workflow enforcement)
-4d. Preserve any existing hooks and settings — never overwrite user's custom configuration
-
-**Step 5: Report**
-Output summary: platform detected, tech stack detected (with detail), modules discovered, L1 docs generated, platform-specific configuration applied, next recommended steps.
+**Phase 7: Project Brief Generation**
+
+If action for project brief == skip, output "Project brief: skipped (exists)" and proceed to Phase 8 (Report).
+
+Otherwise, generate a project brief to capture the user's overall product vision. This file is referenced by `root.prizm` so every new AI session understands the project goals.
+
+→ Read `${SKILL_DIR}/assets/project-brief-template.md` for the brief format rules and checklist template.
+
+**Brownfield** (existing codebase):
+1. Infer project goals from:
+   - Generated `root.prizm` (tech stack, module structure, module groups)
+   - `README.md` (if exists)
+   - Package metadata (`package.json` description, `pyproject.toml`, etc.)
+   - Quick scan of key entry points identified in L1 docs
+2. Generate a draft in the checklist format defined in the template
+3. Present the draft to the user and ask:
+   - Is this inference correct?
+   - Anything to add, remove, or modify?
+4. Apply user edits and write to `.prizmkit/plans/project-brief.md`
+
+**Greenfield** (new/empty project):
+1. Use **progressive questioning** (defined in template) to fully understand the user's intent:
+   - Round 1: Problem & Vision → Round 2: Scope & Features → Round 3: Technical Constraints → Round 4: Clarification (adaptive)
+   - Stop when completion criteria are met: problem, users, core features, boundaries, and technical direction are all clear
+   - If answers are vague, probe deeper — don't accept shallow responses
+2. Generate brief from answers in checklist format
+3. Present to user for confirmation/editing
+4. Write to `.prizmkit/plans/project-brief.md`
+
+**After writing the brief**:
+- Check if `root.prizm` already contains a `PROJECT_BRIEF:` line
+- If exact match `PROJECT_BRIEF: .prizmkit/plans/project-brief.md` exists: skip (already correct)
+- If `PROJECT_BRIEF:` exists with a different path: warn user and ask to confirm update or keep old path
+- If not present: add `PROJECT_BRIEF: .prizmkit/plans/project-brief.md` at the end of `root.prizm`, after all standard sections
+- This ensures every AI session that loads L0 knows to read the project brief
+
+**Phase 8: Report**
+Output summary: platform detected, tech stack detected (with detail), modules discovered, L1 docs generated, project brief status, next recommended steps.
 
 Tech stack report format (only show detected fields, adapt to project type):
 ```
@@ -114,37 +165,16 @@ Adapt fields to match project type — only show detected fields.
 
 Saved to: `.prizmkit/config.json` → `tech_stack` field
 
-Include platform-specific guidance:
-- CodeBuddy: "Use `/prizmkit-plan` to start your first feature"
-- Claude Code: "Use `/prizmkit-plan` to start your first feature"
+Next step: "Use `/prizmkit-plan` to start your first feature"
 
 GREENFIELD WORKFLOW (new project):
-- Skip Step 1 (no code to scan) — but ask the user about their intended tech stack:
+- Skip Phase 4 (no code to scan) — but ask the user about their intended tech stack:
   - "What language/framework will you use?" (e.g. React + Node.js, Python + FastAPI, etc.)
   - Record answers in `config.json` `tech_stack` with `"_auto_detected": false` (user-provided, not auto-detected)
   - If user is unsure, skip tech_stack — it can be populated later on re-init after code exists
-- Step 2: Create minimal `.prizm-docs/` with just `root.prizm` skeleton (populate TECH_STACK from user answers if provided)
-- Steps 3-5: Same as brownfield (Step 5 Report recommends starting with specify for first feature)
-
-### Gradual Adoption Path
-After init, PrizmKit operates in phases:
-- **Passive** (default): Generates docs, doesn't enforce workflow
-- **Advisory**: Suggests improvements, flags issues (enable in config)
-- **Active**: Enforces spec-driven workflow for new features (enable in config)
-
-User can change mode in `.prizmkit/config.json`: `"adoption_mode": "passive" | "advisory" | "active"`
-
-### Platform Reference
-
-| Concept | CodeBuddy | Claude Code |
-|---------|-----------|-------------|
-| Command invocation | `/prizmkit-xxx` | `/prizmkit-xxx` |
-| Project knowledge | `.prizm-docs/` | `.prizm-docs/` |
-| Settings | `.codebuddy/settings.json` | `.claude/settings.json` |
-| Skills/Commands | `.codebuddy/skills/` | `.claude/commands/` |
-| Agents | `.codebuddy/agents/` | `.claude/agents/` |
-| Rules | hooks in settings.json | `.claude/rules/*.md` |
-| CLI command | `cbc` | `claude` |
+- Phase 5: Create minimal `.prizm-docs/` with just `root.prizm` skeleton (populate TECH_STACK from user answers if provided)
+- Phase 7: Generate project brief (greenfield flow — ask user about project goals, see Phase 7 above)
+- Phases 6, 8: Same as brownfield (Phase 8 Report recommends `/prizmkit-plan` for first feature)
 
 ## Example
 
@@ -153,6 +183,12 @@ User can change mode in `.prizmkit/config.json`: `"adoption_mode": "passive" | "
 $ /prizmkit-init
 
 Platform detected: Claude Code
+Init Status Check:
+  [missing] .prizm-docs/
+  [missing] .prizmkit/config.json
+  [missing] .prizmkit/plans/project-brief.md
+→ All missing, generating everything.
+
 Mode: Brownfield (154 source files found)
 
 Tech stack detected:
@@ -171,8 +207,10 @@ Modules discovered:
   src/services/   → .prizm-docs/services.prizm (15 files)
   src/middleware/  → .prizm-docs/middleware.prizm (5 files)
 
+Project brief: inferred from codebase → confirmed by user
+  → .prizmkit/plans/project-brief.md
+
 Generated: root.prizm + 4 L1 docs + changelog.prizm
-Configured: .claude/rules/ (2 files), hooks in settings.json
 Saved: .prizmkit/config.json (tech_stack recorded)
 
 Next: Use /prizmkit-plan to start your first feature
@@ -185,8 +223,14 @@ UPDATE SUPPLEMENT (runs after tech stack merge in Update mode):
 ```
 $ /prizmkit-init
 
-.prizm-docs/ already exists. Reinitialize or update?
-> Update (preserve existing docs)
+Init Status Check:
+  [exists]  .prizm-docs/          (12 files)
+  [exists]  .prizmkit/config.json
+  [missing] .prizmkit/plans/project-brief.md
+
+Missing items will be generated.
+For existing items: [A] Regenerate all  [B] Only generate missing (default)  [C] Pick per item
+> B (Only generate missing)
 
 Tech stack changes detected:
   + bundler: Vite (newly detected)
@@ -199,5 +243,8 @@ Documentation gap-fill:
   = routes.prizm (L1) — up to date
   ~ models.prizm (L1) — FILES count updated (8 → 10)
 
+Project brief: inferred from codebase → confirmed by user
+  → .prizmkit/plans/project-brief.md (generated)
+
 Merged into .prizmkit/config.json (2 fields updated, user overrides preserved)
 ```

package/bundled/skills/prizmkit-init/assets/project-brief-template.md

@@ -0,0 +1,82 @@
+# Project Brief Template
+
+> Capture the user's key product ideas as a simple checklist. Each line is one idea. This file is referenced by `root.prizm` (`PROJECT_BRIEF:`) so every new AI session automatically knows the project's goals.
+
+## File Location
+
+`.prizmkit/plans/project-brief.md`
+
+## Format
+
+```markdown
+# Project Brief
+
+[ ] Core product idea or constraint
+[ ] Another product idea
+[ ] Third idea — one sentence, no sub-bullets
+[x] Already implemented feature -> src/feature/, src/utils/helper.ts
+```
+
+## Rules
+
+1. **First line**: `# Project Brief`
+2. **Remaining lines**: One idea per line, prefixed with `[ ]` (pending) or `[x]` (done)
+3. Each line is **one sentence** — no paragraphs, no sub-bullets, no grouping headers
+4. Language: match the user's language (Chinese or English)
+5. **Size limit**: 500 words max (this file is injected into every session's context window)
+6. **Completion marking** (mandatory): When a brief item is implemented:
+   - Change `[ ]` to `[x]`
+   - Append `->` followed by the **key file or directory paths** that implement it
+   - List the most important 1-3 paths only (entry point, core module, or directory) — not every touched file
+   - Example: `[x] User authentication with OAuth -> src/auth/, src/middleware/auth.ts`
+   - This lets future AI sessions instantly locate the implementation without re-scanning
+
+## Brownfield Init
+
+When initializing an existing project, AI infers the brief from:
+- Generated `root.prizm` (tech stack, module structure)
+- `README.md` (if exists)
+- Package metadata (`package.json` description, `pyproject.toml`, etc.)
+
+Then presents the draft to the user for confirmation and editing.
+
+## Greenfield Init
+
+When initializing a new/empty project, use **progressive questioning** to fully understand the user's intent before generating the brief. Do NOT dump all questions at once — ask in rounds, adapting based on answers.
+
+### Round 1: Problem & Vision (required)
+- What problem does this project solve? (or: what's the core idea?)
+- Who is the target user / audience?
+
+### Round 2: Scope & Features (required)
+- What are the 3-5 core features or capabilities? (ask user to list them)
+- What is the MVP scope? (what's the minimum version that delivers value?)
+- Are there any explicit non-goals? (things this project deliberately does NOT do)
+
+### Round 3: Technical Constraints (if user has preferences)
+- Any preferred tech stack / language / framework?
+- Any integration requirements? (third-party APIs, databases, auth providers)
+- Deployment target? (web app, mobile, CLI, library, self-hosted, cloud)
+
+### Round 4: Clarification (adaptive — only if gaps remain)
+If previous answers are vague or incomplete, probe deeper:
+- "You mentioned X — can you give a concrete example of how a user would use it?"
+- "Are there existing tools that do something similar? How is yours different?"
+- "What does success look like for V1?"
+
+### Completion Criteria
+Stop asking when ALL of these are clear:
+1. **Problem** — what pain point or opportunity this addresses
+2. **Users** — who will use it and in what context
+3. **Core features** — at least 3 concrete capabilities (not vague aspirations)
+4. **Boundaries** — what's in scope vs. out of scope for V1
+5. **Technical direction** — enough to populate `config.json` tech_stack (or explicitly deferred)
+
+If the user gives short/vague answers, don't accept them — rephrase and ask again. A weak brief leads to weak specs downstream.
+
+### Generate & Confirm
+Once all criteria are met:
+1. Generate brief in checklist format (see Format section above)
+2. Present to user with: "Here's what I captured — anything to add, remove, or change?"
+3. Apply edits and write to `.prizmkit/plans/project-brief.md`
+