@baoanaz/cviauto 0.6.5

package/dist/templates/common/commands/continue.md

@@ -0,0 +1,57 @@
+# Continue Current Task
+
+Resume work on the current task — pick up at the right phase/step in `.cviauto/workflow.md`.
+
+---
+
+## Step 1: Load Current Context
+
+```bash
+{{PYTHON_CMD}} ./.cviauto/scripts/get_context.py
+```
+
+Confirms: current task, git state, recent commits.
+
+## Step 2: Load the Phase Index
+
+```bash
+{{PYTHON_CMD}} ./.cviauto/scripts/get_context.py --mode phase
+```
+
+Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
+
+## Step 3: Decide Where You Are
+
+`get_context.py` shows the active task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Cviauto flow; it does not itself approve implementation.
+
+- `status=planning` + no `prd.md` → **1.1** (load `cviauto-brainstorm`)
+- `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
+- `status=planning` + complex artifacts complete + sub-agent jsonl not curated (only the seed `_example` row) → **1.3**
+- `status=planning` + required artifacts complete + required jsonl curated or inline mode → **1.4** (ask for start review; only run `task.py start` after user confirms)
+- `status=in_progress` + implementation not started → **2.1**
+- `status=in_progress` + implementation done, not yet checked → **2.2**
+- `status=in_progress` + check passed + no explicit spec-promotion request → **3.4** (commit)
+- `status=in_progress` + check passed + user explicitly asks to "沉淀 spec" / update spec → **3.3** (spec update proposal) → **3.4** (commit)
+- `status=completed` (rare; usually archived immediately) → archive flow
+
+Phase rules (full detail in `.cviauto/workflow.md`):
+
+1. Run steps **in order** within a phase — `[required]` steps must not be skipped
+2. `[once]` steps are already done if the required output exists. `prd.md` alone can be enough only for lightweight tasks; complex tasks also need `design.md` and `implement.md`.
+3. You may go back to an earlier phase if discoveries require it
+
+## Step 4: Load the Specific Step
+
+Once you know which step to resume at:
+
+```bash
+{{PYTHON_CMD}} ./.cviauto/scripts/get_context.py --mode phase --step <X.X> --platform {{CLI_FLAG}}
+```
+
+Follow the loaded instructions. After each `[required]` step completes, move to the next.
+
+---
+
+## Reference
+
+Full workflow and detailed phase steps live in `.cviauto/workflow.md`. This command is only an entry point — the canonical guidance is there.

package/dist/templates/common/commands/finish-work.md

@@ -0,0 +1,74 @@
+# Finish Work
+
+Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal as local Cviauto records. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this command.
+
+If the user explicitly asks to promote current-session knowledge into spec (for example, "finish-work and write the rule about X into spec"), complete the optional spec-promotion flow before archiving:
+
+1. Load `cviauto-update-spec`.
+2. Propose the target `.cviauto/spec/` file and exact reusable rule.
+3. Write the spec update only after user confirmation.
+4. Then continue with the normal archive + journal steps below.
+
+## Step 1: Survey current state
+
+```bash
+{{PYTHON_CMD}} ./.cviauto/scripts/get_context.py --mode record
+```
+
+This prints:
+
+- **My active tasks** — review whether any besides the current one are actually done (code merged, AC met) and should be archived this round.
+- **Git status** — quick visual on what's dirty.
+- **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
+
+If `--mode record` surfaces other completed tasks not tied to the current session, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the current active task is always archived in Step 3 regardless.
+
+## Step 2: Sanity check — classify dirty paths
+
+Run:
+
+```bash
+git status --porcelain
+```
+
+Filter out paths under `.cviauto/workspace/` and `.cviauto/tasks/` — those are local Cviauto task/session records and should not block finish-work unless they contain changes the user explicitly wants to publish.
+
+For each remaining dirty path, decide whether it belongs to **the current task** or to **other parallel work** (e.g., another terminal window editing the same repo). Heuristics:
+
+- Paths referenced in the current task's `prd.md` / `implement.jsonl` / `check.jsonl` → current task
+- Paths in code areas matching the task's stated scope, or that you remember editing this session → current task
+- Paths in unrelated areas you have no recollection of touching this session → other parallel work
+
+Then route:
+
+- **Any remaining path looks like current-task work** — bail out with:
+  > "Working tree has uncommitted code changes from this task: `<list>`. Return to workflow Phase 3.4 to commit them before running `{{CMD_REF:finish-work}}`."
+
+  Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Phase 3.4 and the AI drives the batched commit there.
+- **All remaining paths look unrelated** (other parallel-window work) — report them once and continue to Step 3:
+  > "FYI, dirty files outside this task's scope — leaving them for the other window: `<list>`."
+- **Genuinely unsure** — ask the user once: "Are `<list>` this task's work I forgot to commit, or another window's? (commit / ignore)" — then route per their answer.
+
+## Step 3: Archive task(s)
+
+```bash
+{{PYTHON_CMD}} ./.cviauto/scripts/task.py archive <task-name> --no-commit
+```
+
+At minimum: the current active task (if any). Plus any extra tasks the user confirmed in Step 1. Archives are local Cviauto records by default; do not create a `chore(task): archive ...` commit unless the user explicitly asks to publish Cviauto bookkeeping.
+
+If there is no active task and the user did not confirm any cleanup archives, skip this step.
+
+## Step 4: Record session journal
+
+```bash
+{{PYTHON_CMD}} ./.cviauto/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary" \
+  --no-commit
+```
+
+Use the work-commit hashes produced in Phase 3.4 (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. This records the session locally and does not create a `chore: record journal` commit.
+
+Final git history by default: work commits only. Archive and journal files stay local unless the user explicitly asks to publish Cviauto bookkeeping.

package/dist/templates/common/commands/start.md

@@ -0,0 +1,59 @@
+# Start Session
+
+Initialize a Cviauto-managed development session. This platform has no session-start hook, so manually load the equivalent compact context by following these steps.
+
+---
+
+## Step 1: Current state
+Identity, git status, current task, active tasks, journal location.
+
+```bash
+{{PYTHON_CMD}} ./.cviauto/scripts/get_context.py
+```
+
+If this output includes a line beginning `Cviauto update available:`, copy the full line verbatim when summarizing session context. Do not shorten operational command hints.
+
+## Step 2: Workflow overview
+Compact Phase Index, request triage rules, planning artifact contract, and the step-detail command.
+
+```bash
+{{PYTHON_CMD}} ./.cviauto/scripts/get_context.py --mode phase
+```
+
+Full guide in `.cviauto/workflow.md` (read on demand).
+
+## Step 3: Guideline indexes
+Discover packages + spec layers, then read each relevant index file.
+
+```bash
+{{PYTHON_CMD}} ./.cviauto/scripts/get_context.py --mode packages
+cat .cviauto/spec/guides/index.md
+cat .cviauto/spec/<package>/<layer>/index.md   # for each relevant layer
+```
+
+Index files list the specific guideline docs to read when you actually start coding.
+
+## Step 4: Decide next action
+From Step 1 you know the current task and status. Check the task directory:
+
+- **Active task status `planning` + no `prd.md`** → Phase 1.1. Load the `cviauto-brainstorm` skill.
+- **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. Load the relevant Phase 1 step detail before `task.py start`.
+- **Active task status `in_progress`** → Phase 2 step 2.1. Load the step detail:
+  ```bash
+  {{PYTHON_CMD}} ./.cviauto/scripts/get_context.py --mode phase --step 2.1 --platform {{CLI_FLAG}}
+  ```
+- **No active task** → classify first. For simple conversation / small task, ask only whether this turn should create a Cviauto task. For complex work, ask whether you may create a Cviauto task and enter planning. If the user says no, skip Cviauto for this session.
+
+---
+
+## Skill routing (quick reference)
+
+| User intent | Skill |
+|---|---|
+| New feature / unclear requirements | `cviauto-brainstorm` |
+| About to write code | `cviauto-before-dev` |
+| Done coding / quality check | `cviauto-check` |
+| Stuck / fixed same bug multiple times | `cviauto-break-loop` |
+| Learned something worth capturing | `cviauto-update-spec` |
+
+Full rules + anti-rationalization table in `.cviauto/workflow.md`.

package/dist/templates/common/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Common templates — single source of truth for all platforms.
+ *
+ * These templates contain {{placeholders}} that are resolved per-platform
+ * by resolvePlaceholders() in configurators/shared.ts.
+ *
+ * Directory structure:
+ *   common/
+ *   ├── commands/        # Templates that stay as slash commands
+ *   ├── skills/          # Single-file templates that become auto-triggered skills
+ *   └── bundled-skills/  # Multi-file built-in skills with references/assets
+ */
+export interface CommonTemplate {
+    /** Template name without extension (e.g., "start", "before-dev") */
+    name: string;
+    /** Raw content with {{placeholders}} — must be resolved before writing */
+    content: string;
+}
+export interface CommonBundledSkillFile {
+    /** POSIX path relative to the skill directory, e.g. "references/core.md" */
+    relativePath: string;
+    /** Raw content with {{placeholders}} — must be resolved before writing */
+    content: string;
+}
+export interface CommonBundledSkill {
+    /** Skill directory name, e.g. "cviauto-meta" */
+    name: string;
+    /** Files that must be written under the skill directory */
+    files: CommonBundledSkillFile[];
+}
+/**
+ * Get all command templates (stay as slash commands on all platforms).
+ * Results are cached after first call.
+ */
+export declare function getCommandTemplates(): CommonTemplate[];
+/**
+ * Get all skill templates (become auto-triggered skills on supporting platforms).
+ * Results are cached after first call.
+ */
+export declare function getSkillTemplates(): CommonTemplate[];
+/**
+ * Get all multi-file built-in skills.
+ *
+ * These are copied as complete skill directories so references and assets stay
+ * lazy-loadable instead of being flattened into one oversized SKILL.md.
+ */
+export declare function getBundledSkillTemplates(): CommonBundledSkill[];
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAMpD;AAuCD;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,EAAE,CAM/D"}

package/dist/templates/common/index.js

@@ -0,0 +1,104 @@
+/**
+ * Common templates — single source of truth for all platforms.
+ *
+ * These templates contain {{placeholders}} that are resolved per-platform
+ * by resolvePlaceholders() in configurators/shared.ts.
+ *
+ * Directory structure:
+ *   common/
+ *   ├── commands/        # Templates that stay as slash commands
+ *   ├── skills/          # Single-file templates that become auto-triggered skills
+ *   └── bundled-skills/  # Multi-file built-in skills with references/assets
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function readTemplate(relativePath) {
+    return readFileSync(join(__dirname, relativePath), "utf-8");
+}
+function listMarkdownFiles(dir) {
+    try {
+        return readdirSync(join(__dirname, dir))
+            .filter((f) => f.endsWith(".md"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+// Cached results — files don't change during a CLI run
+let cachedCommands;
+let cachedSkills;
+let cachedBundledSkills;
+/**
+ * Get all command templates (stay as slash commands on all platforms).
+ * Results are cached after first call.
+ */
+export function getCommandTemplates() {
+    cachedCommands ??= listMarkdownFiles("commands").map((file) => ({
+        name: file.replace(/\.md$/, ""),
+        content: readTemplate(`commands/${file}`),
+    }));
+    return cachedCommands;
+}
+/**
+ * Get all skill templates (become auto-triggered skills on supporting platforms).
+ * Results are cached after first call.
+ */
+export function getSkillTemplates() {
+    cachedSkills ??= listMarkdownFiles("skills").map((file) => ({
+        name: file.replace(/\.md$/, ""),
+        content: readTemplate(`skills/${file}`),
+    }));
+    return cachedSkills;
+}
+function listDirectories(dir) {
+    try {
+        return readdirSync(join(__dirname, dir))
+            .filter((entry) => statSync(join(__dirname, dir, entry)).isDirectory())
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function toPosixRelativePath(root, filePath) {
+    return relative(root, filePath).split(sep).join("/");
+}
+function listBundledSkillFiles(skillDir) {
+    const root = join(__dirname, "bundled-skills", skillDir);
+    const files = [];
+    function walk(dir) {
+        for (const entry of readdirSync(dir)) {
+            const fullPath = join(dir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+            }
+            else {
+                files.push({
+                    relativePath: toPosixRelativePath(root, fullPath),
+                    content: readFileSync(fullPath, "utf-8"),
+                });
+            }
+        }
+    }
+    walk(root);
+    return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+/**
+ * Get all multi-file built-in skills.
+ *
+ * These are copied as complete skill directories so references and assets stay
+ * lazy-loadable instead of being flattened into one oversized SKILL.md.
+ */
+export function getBundledSkillTemplates() {
+    cachedBundledSkills ??= listDirectories("bundled-skills").map((name) => ({
+        name,
+        files: listBundledSkillFiles(name),
+    }));
+    return cachedBundledSkills;
+}
+//# sourceMappingURL=index.js.map

package/dist/templates/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/common/skills/before-dev.md

@@ -0,0 +1,35 @@
+Read the relevant development guidelines before starting your task.
+
+Execute these steps:
+
+1. **Read current task artifacts**:
+   - `prd.md` for requirements and acceptance criteria
+   - `design.md` if present for technical design
+   - `implement.md` if present for execution order and validation plan
+
+2. **Discover packages and their spec layers**:
+   ```bash
+   python3 ./.cviauto/scripts/get_context.py --mode packages
+   ```
+
+3. **Identify which specs apply** to your task based on:
+   - Which package you're modifying (e.g., `cli/`, `docs-site/`)
+   - What type of work (backend, frontend, unit-test, docs, etc.)
+   - Any spec/research paths referenced by the task artifacts
+
+4. **Read the spec index** for each relevant module:
+   ```bash
+   cat .cviauto/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Pre-Development Checklist"** section in the index.
+
+5. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
+
+6. **Always read shared guides**:
+   ```bash
+   cat .cviauto/spec/guides/index.md
+   ```
+
+7. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
+
+This step is **mandatory** before writing any code.

package/dist/templates/common/skills/brainstorm.md

@@ -0,0 +1,168 @@
+# Cviauto Brainstorm
+
+## Non-Negotiable Interview Contract
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+## Non-Negotiable Evidence Rule
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+This is mandatory. Before asking the user a question, first check whether the answer is already available in code, tests, configs, docs, existing specs, or task history.
+
+Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, or decisions that remain ambiguous after inspection.
+
+---
+
+Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
+
+## Preconditions
+
+Use this skill only after task-creation consent has been given and the user is ready to enter Cviauto planning.
+
+If no task exists yet, create one:
+
+```bash
+TASK_DIR=$({{PYTHON_CMD}} ./.cviauto/scripts/task.py create "<short task title>" --slug <slug>)
+```
+
+Use a concise title from the user's request. Use a slug without a date prefix. `task.py create` adds the `MM-DD-` directory prefix automatically.
+
+`task.py create` creates the default `prd.md`. Update that file with the current understanding before asking follow-up questions.
+
+## Planning Flow
+
+1. Capture the user's request and initial known facts in `prd.md`.
+2. Inspect available evidence before asking questions:
+   - code, tests, fixtures, and configs
+   - README files, docs, existing specs, and domain notes
+   - related Cviauto tasks, research files, and session history when present
+3. Separate what you found into:
+   - confirmed facts
+   - product intent still needed from the user
+   - scope or risk decisions still needed from the user
+   - likely out-of-scope items
+4. Ask the single highest-value remaining question.
+5. Include your recommended answer with the question.
+6. After each user answer, update `prd.md` before continuing.
+7. For complex tasks, create or update `design.md` and `implement.md` before implementation starts.
+8. Before final review or `task.py start`, run the PRD convergence pass below.
+
+Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
+
+## Question Rules
+
+Ask only one question per message.
+
+Each question must include:
+
+- the decision needed
+- why the answer matters
+- your recommended answer
+- the trade-off if the user chooses differently
+
+Do not ask process questions such as whether to search, inspect files, or continue brainstorming. Do the evidence work directly. Ask the user only when the remaining issue is a product decision, preference, scope boundary, or risk tolerance choice.
+
+## Thinking Framework: First Principles Analysis
+
+When requirements are vague, solutions feel over-engineered, or you're about to add complexity "because everyone does" — decompose to fundamental truths before reasoning upward.
+
+### Step 1: Restate the Problem
+
+Strip away implementation details to one sentence.
+
+> Bad: "We need to add Redis caching to the user profile endpoint"
+> Good: "User profile data takes too long to load"
+
+### Step 2: List Fundamental Truths
+
+What is absolutely true (not opinion or convention)?
+
+| Category | Examples |
+|----------|----------|
+| **Physical constraints** | Network latency ≥ 0, disk I/O has limits |
+| **Business rules** | "Users must see their own data" |
+| **Technical invariants** | "Data must be consistent" |
+| **User needs** | "The user wants X within Y seconds" |
+
+### Step 3: Challenge Assumptions
+
+For each component of the current plan:
+
+- **Fact or convention?** "We always use REST" — why?
+- **What if we removed this?** If nothing breaks, it's unnecessary.
+- **Solving the actual problem or a symptom?** Trace the causal chain.
+- **Who benefits from this complexity?** If "nobody", simplify.
+
+### Step 4: Build Up from Truths
+
+1. Start with the minimum viable mechanism satisfying all truths
+2. Add complexity only when a specific truth demands it
+3. Each addition must answer: "Which truth requires this?"
+
+### Step 5: Validate
+
+- Does the solution solve the original problem?
+- What assumptions need verification?
+- What's the simplest experiment to test this?
+
+## Artifact Rules
+
+`prd.md` records requirements and acceptance:
+
+- goal and user value
+- confirmed facts
+- requirements
+- acceptance criteria
+- out of scope
+- open questions that still block planning
+
+`design.md` records technical design for complex tasks:
+
+- architecture and boundaries
+- data flow and contracts
+- compatibility and migration notes
+- important trade-offs
+- operational or rollback considerations
+
+`implement.md` records execution planning for complex tasks:
+
+- ordered implementation checklist
+- validation commands
+- risky files or rollback points
+- follow-up checks before `task.py start`
+
+Lightweight tasks may have only `prd.md`. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
+
+`implement.md` is not a replacement for `implement.jsonl`. On sub-agent-dispatch workflows, `implement.jsonl` and `check.jsonl` must each contain at least one real spec/research entry before `task.py start`; the seed `_example` row does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through `cviauto-before-dev`.
+
+## PRD Convergence Pass
+
+Before declaring planning ready or running `task.py start`, rewrite `prd.md` once against the final structure described in the artifact rules above. This is not optional cleanup; it is the final planning gate.
+
+The pass must be lossless:
+
+- Collapse repeated facts into one authoritative section.
+- Fold temporary brainstorm sections such as `What I already know`, `Assumptions`, and resolved `Open Questions` into Goal, Background, Requirements, Technical Notes, or Acceptance Criteria.
+- Remove resolved open questions instead of leaving empty or already-answered sections.
+- Merge parallel bug and requirement lists when they describe the same work; keep each defect's severity, evidence, and file:line anchors on the owning requirement.
+- Preserve every file:line anchor, decision, constraint, requirement ID, and acceptance-criteria mapping.
+- Keep only genuinely blocking open questions.
+
+After the pass, read `prd.md` top to bottom and verify that no fact is repeated across sections unless the repetition adds new information.
+
+## Quality Bar
+
+Before declaring planning ready:
+
+- `prd.md` contains testable acceptance criteria.
+- `prd.md` has passed the PRD convergence pass: no unresolved temporary brainstorm sections, no duplicate facts across sections, and no lost anchors, decisions, or acceptance mappings.
+- Repository-answerable questions have already been answered through inspection.
+- Remaining open questions are genuinely about user intent or scope.
+- Complex tasks have `design.md` and `implement.md`.
+- Sub-agent-dispatch tasks have real curated entries in both `implement.jsonl` and `check.jsonl`; seed-only manifests are not ready.
+- The user has reviewed the final planning artifacts or explicitly approved proceeding.
+
+Do not start implementation until the user approves or asks for implementation.