@baoanaz/cviauto 0.6.5

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/skills-and-commands.md

@@ -0,0 +1,85 @@
+# Skills, Commands, Prompts, And Workflows
+
+Skills and commands are textual entry points for user interaction with Cviauto. Different platforms use different names, but their core purpose is the same: tell the AI how to enter the Cviauto flow when the user expresses a certain intent.
+
+## Conceptual Differences
+
+| Type | Trigger mode | Best for |
+| --- | --- | --- |
+| skill | AI auto-match or explicit user mention | Long-term capabilities, workflow rules, modification guides. |
+| command | Explicit user invocation | Clear operation entry points such as continue and finish-work. |
+| prompt | Explicit user invocation or platform selection | Similar to command, but in a platform prompt format. |
+| workflow | Explicit user selection or platform auto-match | Guides the main session when no sub-agent/hook exists. |
+
+Cviauto workflow skills usually share one semantic set: brainstorm, before-dev, check, update-spec, break-loop. Multi-file built-in skills such as `cviauto-meta` use layered references.
+
+## Common Paths
+
+| Platform | Common entries |
+| --- | --- |
+| Claude Code | `.claude/skills/`, `.claude/commands/` |
+| Cursor | `.cursor/skills/`, `.cursor/commands/` |
+| OpenCode | `.opencode/skills/`, `.opencode/commands/` |
+| Codex | `.agents/skills/`, `.codex/skills/` |
+| Kilo | `.kilocode/skills/`, `.kilocode/workflows/` |
+| Kiro | `.kiro/skills/` |
+| Gemini CLI | `.agents/skills/`, `.gemini/commands/` |
+| Antigravity | `.agent/skills/`, `.agent/workflows/` |
+| Devin | `.devin/skills/`, `.devin/workflows/` |
+| Qoder | `.qoder/skills/`, `.qoder/commands/` |
+| CodeBuddy | `.codebuddy/skills/`, `.codebuddy/commands/` |
+| GitHub Copilot | `.github/skills/`, `.github/prompts/` |
+| Factory Droid | `.factory/skills/`, `.factory/commands/` |
+| Pi Agent | `.pi/skills/` |
+| Reasonix | `.reasonix/skills/` |
+| ZCode | `.agents/skills/`, `.zcode/commands/` |
+
+In a user project, use the files actually generated by init as authoritative.
+
+## Skill Structure
+
+A common skill is a directory:
+
+```text
+cviauto-meta/
+├── SKILL.md
+└── references/
+```
+
+`SKILL.md` should tell the AI:
+
+- When to use this skill.
+- Which reference to read first for the current task.
+- What not to do.
+
+References hold longer explanations so the entry file does not contain everything.
+
+## Command/Prompt/Workflow Structure
+
+Commands, prompts, and workflows are usually single files. Their content should include:
+
+- When to use it.
+- Which `.cviauto/` files to read.
+- Which scripts to run.
+- How to report after completion.
+
+They should not store task state; task state belongs in `.cviauto/tasks/` and `.cviauto/.runtime/`.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| Change AI auto-trigger rules | The corresponding skill's frontmatter description. |
+| Change user command behavior | The corresponding command/prompt/workflow file. |
+| Add a project-local skill | Platform skill directory, or shared `.agents/skills/`. |
+| Let multiple platforms share one capability | Write equivalent skills in each platform skill directory, or use the `.agents/skills/` shared layer on platforms that support it. |
+| Change finish/continue entry points | Platform commands/prompts/workflows. |
+
+## Modification Principles
+
+1. **Keep entry files short; references carry long content**. This matters especially for multi-file skills like `cviauto-meta`.
+2. **Make trigger descriptions specific**. A description that is too broad can mis-trigger; one that is too narrow may not trigger.
+3. **Keep the same semantics consistent across platforms**. File formats can differ, but behavior descriptions should match.
+4. **Put project-specific capabilities in local skills**. Do not put team-private flows into public `cviauto-meta`.
+
+If the user only wants local AI to know one more project rule, usually create a project-local skill or update `.cviauto/spec/` instead of changing a Cviauto built-in workflow skill.

package/dist/templates/common/bundled-skills/trellis-session-insight/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: cviauto-session-insight
+description: "Reach into past AI conversation history through the `cviauto mem` CLI. Use whenever the user asks 'how did we solve X last time', 'have we discussed this before', 'what was the decision on X', 'remind me what we did in this task', '上次怎么解的', '之前讨论过吗', '想起一段对话', or when starting a brainstorm that overlaps prior work, debugging a familiar bug, continuing a task across sessions, or doing a finish-work review. Returns raw past dialogue; decide for the moment whether to update spec, append to task notes, quote inline in the answer, or just internalize."
+---
+
+# Cviauto Session Insight
+
+This skill teaches an AI **how to call `cviauto mem`** — the project's cross-session memory feedstock — and **when reaching for it is the right move**.
+
+It is intentionally a **capability skill, not a workflow**. There is no fixed output file, no required write-back step, no "always run after finish-work" rule. What to do with what `mem` returns is a judgement call made in the moment of the conversation. The skill exists so the AI knows the capability is there and can decide.
+
+## What `cviauto mem` is
+
+A local CLI that indexes the user's past Claude Code, Codex, and Pi Agent conversation logs (the JSONL files each platform stores under `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/`) and lets you list, search, slice by Cviauto task boundaries, and dump cleaned dialogue from them. OpenCode logs are not yet indexable (provider adapter pending) — when an OpenCode session is the obvious target, surface that limitation rather than guessing.
+
+Nothing in `mem` is uploaded. All reads are local.
+
+## When to reach for it
+
+The bar is "would a senior teammate ask 'didn't we already talk about this?'" — those are the moments. Some concrete patterns:
+
+- **Brainstorm rerun risk.** Starting a new task that touches an area the user has been in before, and you want to check whether a decision was already made — before re-asking the user.
+- **Familiar-bug debugging.** The current bug pattern feels like one the user reported / fixed before. Pulling the relevant past session can save a full debugging loop.
+- **Cross-session continuation.** The user resumes work after a gap and says "where were we" / "继续上次的" without being specific.
+- **Decision retrieval.** The user references "the decision we made about X" but the decision lives in an old brainstorm, not in any `prd.md` / `spec/`.
+- **Finish-work retrospective.** When the user explicitly asks for a wrap-up of what was decided / what hurt / what surprised them in this task — not as a forced step on every finish-work.
+- **Pattern-spotting across past work.** The user asks "do I keep making the same mistake on X" / "我每次都踩这个坑吗" — search across sessions answers that.
+
+If none of these apply, don't call `mem`. It is a tool, not a ceremony.
+
+## When NOT to reach for it
+
+- The relevant context is already in the current turn, `prd.md`, `design.md`, recent `git log`, or the open files. `mem` is for stuff that has fallen out of immediate reach.
+- The user is asking about a fact in the code, not a fact from a past conversation. `git log -p` / `grep` / reading the file directly is faster and more authoritative.
+- You are in a sub-agent (`cviauto-implement` / `cviauto-check`) whose dispatch prompt already includes the curated `implement.jsonl` / `check.jsonl` context. Adding `mem` on top usually just clutters.
+- The user has explicitly said "don't dig through history, just answer what I asked".
+
+## What to do with what `mem` returns
+
+Treat the output as **raw material**, not a deliverable. Once you have it, decide based on the live conversation:
+
+- **Quote inline in your reply** if a specific past exchange answers the user's current question — and cite the session-id / phase so the user can verify.
+- **Update `<task>/prd.md` or `<task>/design.md`** if `mem` surfaced a load-bearing decision that should have been written down but wasn't. Surface the proposed edit to the user first.
+- **Append to a task-local notes file** (e.g. `<task>/notes.md` or extending an existing one) if the finding belongs to the current task's record but doesn't fit the PRD.
+- **Update `.cviauto/spec/`** if the finding is a project-wide convention or gotcha that would help future tasks. Run the `cviauto-update-spec` skill for that — `session-insight` ends at the discovery.
+- **Just absorb it** for the next few turns and answer better, without writing anything. This is often the right move for one-off recall.
+
+Cviauto does not prescribe a single destination. Forcing every recall into a fixed file makes the file grow into noise. Let the situation decide.
+
+## How to call it
+
+Full CLI reference is in `references/cli-quick-reference.md`. The 80% case is one of:
+
+```bash
+# Find sessions whose contents mention a keyword (project-scope is default;
+# add --global to search every project on this machine).
+cviauto mem search "<keyword>"
+
+# Dump dialogue from one session, optionally filtered by phase or keyword.
+cviauto mem extract <session-id> --phase brainstorm
+cviauto mem extract <session-id> --grep "<keyword>"
+
+# Drill into a session: top-N hit turns + surrounding context.
+cviauto mem context <session-id> --turns 3 --around 2
+
+# When you do not know the session id yet, start with list + filter.
+cviauto mem list --cwd <project-path>
+cviauto mem projects   # → list active project cwds, then narrow
+```
+
+Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
+
+## Triggering patterns
+
+`references/triggering-patterns.md` lists more verbatim user phrasings (English + Chinese) that should make you think "reach for `mem`" — keep that handy when training instinct.
+
+## Out of scope
+
+- `mem` does not edit code or update files. Any write-back is your decision in the moment.
+- `mem` is read-only on the platform JSONL stores. It does not push or sync to remote.
+- This skill does not replace `cviauto-update-spec` (which is the right tool for promoting a finding into project-wide guidance) or the platform-native task / spec workflow.

package/dist/templates/common/bundled-skills/trellis-session-insight/references/cli-quick-reference.md

@@ -0,0 +1,65 @@
+# `cviauto mem` CLI Reference
+
+Full flag reference for the five subcommands. Pin this as the authoritative source — `cviauto mem help` prints the same content at runtime, so anything here that drifts is a bug.
+
+## Subcommands
+
+| Command                | Purpose                                                                                                                |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `list`                 | List sessions. Default subcommand when none is given.                                                                  |
+| `search <keyword>`     | Find sessions whose contents match a keyword.                                                                          |
+| `context <session-id>` | Drill into one session: top-N hit turns + surrounding context. Pair with `--grep` for keyword anchoring.               |
+| `extract <session-id>` | Dump cleaned dialogue. Combine with `--phase` / `--grep` to slice.                                                     |
+| `projects`             | List active project `cwd` values with session counts. Use this to discover which `--cwd` to pass to other subcommands. |
+
+## Flags (apply where meaningful)
+
+| Flag                                          | Subcommands       | Meaning                                                                                                                                                    |
+| --------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--platform claude\|codex\|opencode\|pi\|all` | all               | Default `all`. OpenCode adapter is currently a stub on `0.6.0-beta.*` — see "Caveats" below.                                                               |
+| `--since YYYY-MM-DD`                          | list / search     | Inclusive lower date bound.                                                                                                                                |
+| `--until YYYY-MM-DD`                          | list / search     | Inclusive upper date bound.                                                                                                                                |
+| `--global`                                    | list / search     | Include sessions from every project on this machine. Default is the current project `cwd`.                                                                 |
+| `--cwd <path>`                                | list / search     | Force a specific project cwd instead of inferring from where you are.                                                                                      |
+| `--limit N`                                   | list / search     | Cap output rows. Default `50`.                                                                                                                             |
+| `--grep KW`                                   | extract / context | Filter turns by keyword. Multi-token AND when whitespace-separated.                                                                                        |
+| `--phase brainstorm\|implement\|all`          | extract           | Slice session by Cviauto task boundaries. `brainstorm` = `[task.py create, task.py start)`. `implement` = turns outside brainstorm windows. Default `all`. |
+| `--turns N`                                   | context           | Number of hit turns to return. Default `3`.                                                                                                                |
+| `--around N`                                  | context           | Surrounding turns to include per hit. Default `1`.                                                                                                         |
+| `--max-chars N`                               | context           | Total character budget. Default `6000` (~1500 tokens).                                                                                                     |
+| `--include-children`                          | search / context  | Merge OpenCode sub-agent sessions into their parent session.                                                                                               |
+| `--json`                                      | all               | Emit machine-parseable JSON instead of human-readable output.                                                                                              |
+
+## Common one-liners
+
+```bash
+# What past sessions discussed "deadlock" anywhere on this machine?
+cviauto mem search "deadlock" --global --limit 20
+
+# Inside a specific session, surface the top 5 turns that mention "lock contention"
+# plus 2 turns of surrounding context.
+cviauto mem context 5842592d --grep "lock contention" --turns 5 --around 2
+
+# Recover the brainstorm window for a session — useful when continuing a task
+# the user started a week ago.
+cviauto mem extract 5842592d --phase brainstorm
+
+# List every project this machine has Cviauto sessions for, with counts.
+cviauto mem projects
+```
+
+## Output shapes
+
+- **Default human output** (no `--json`): wrapped to a terminal, with session ids highlighted and turn markers visible. Suitable to read inline but messy to paste into a markdown file.
+- **`--json`**: stable schema, safe to parse and process. When piping `mem` output into a follow-up step (e.g. summarizing for a Lessons section), prefer `--json`.
+
+## Caveats
+
+- **OpenCode adapter is a stub on `0.6.0-beta.*`.** When `--platform` resolves to OpenCode (or `all` and OpenCode would be included), `mem` prints a one-line "reader unavailable" notice and continues with the other platforms. Don't promise OpenCode coverage in your reply until the adapter ships.
+- **`--phase` slicing depends on `task.py create` / `task.py start` invocations appearing in the recorded bash calls of the session.** Sessions where the user ran `task.py` from a different terminal — outside the recorded AI loop — will not have phase boundaries. `--phase all` is the safe fallback.
+- **`mem` indexes platform JSONL files directly.** If the user has cleared their Claude / Codex / Pi session storage, `mem` cannot recover what is no longer on disk.
+- **`mem` is read-only.** No remote sync, no edits to platform JSONL. Any write you do based on `mem` findings is your own follow-up call into the editing tools available to you.
+
+## When you need more than this reference
+
+Run `cviauto mem help` in the user's shell. The runtime help is authoritative and will be ahead of this reference during fast-moving beta releases.

package/dist/templates/common/bundled-skills/trellis-session-insight/references/triggering-patterns.md

@@ -0,0 +1,93 @@
+# Triggering Patterns
+
+Verbatim user phrasings that should make an AI reach for `cviauto mem`. Calibrate instinct against these — if a user message hits one of these patterns and you do not reach for `mem`, you probably missed an obvious recall.
+
+Patterns are grouped by the *intent* behind the phrasing, not the surface words. The same intent shows up in different languages and registers.
+
+## Past-solution recall
+
+The user is asking "how did we (or I) solve this before". Past dialogue holds the answer; the codebase shows the result but not the reasoning.
+
+- "How did we solve this last time?"
+- "What did we end up doing about X?"
+- "We dealt with this once already, didn't we?"
+- "上次怎么解的?"
+- "之前是怎么搞定 X 的?"
+- "我记得以前修过类似的"
+
+Reach: `cviauto mem search "<symptom keyword>" --global --limit 10`, then `context` into the hit that looks closest.
+
+## Decision retrieval
+
+The user is referencing a decision that lives in old dialogue, not in any committed file. Look in brainstorm windows.
+
+- "What was the decision on X?"
+- "Did we decide to use Postgres or SQLite?"
+- "The rationale for choosing X over Y was…?"
+- "我们当时为啥选了 X 而不是 Y?"
+- "关于 X 我们之前是怎么定的?"
+- "之前讨论过 X 的方案吗?"
+
+Reach: `cviauto mem search "<decision keyword>"` to find the session, then `extract <id> --phase brainstorm` to recover the discussion.
+
+## Cross-session continuation
+
+The user resumed work after a gap and the context is implicit.
+
+- "Where were we?"
+- "Continue from last time."
+- "Pick up where we left off."
+- "继续上次的"
+- "我们上次做到哪了"
+- "接着昨天那个任务"
+
+Reach: `cviauto mem list --task <current-task-dir>` to find the most recent sessions tied to the active task, then `extract` the last one.
+
+## Familiar-bug debugging
+
+The current bug feels like one already seen. Past sessions probably hold the resolution path.
+
+- "I feel like I've hit this before."
+- "Doesn't this look like that bug from last month?"
+- "Same kind of timeout I had in X."
+- "这个错好像之前见过"
+- "这个 bug 是不是上次那个?"
+- "怎么又是这个 error?"
+
+Reach: `cviauto mem search "<error message fragment>" --global`. Anchor on a short, distinctive token from the actual error string.
+
+## Self-pattern spotting
+
+The user is asking whether they keep repeating the same kind of mistake or decision.
+
+- "Do I always make this mistake?"
+- "How often have I run into X?"
+- "Is this a recurring thing for me?"
+- "我每次都踩这个坑吗?"
+- "我老犯这个错?"
+- "这类问题之前出现过几次?"
+
+Reach: `cviauto mem search "<topic>" --global --limit 50` and scan the dates / projects in the listing. Optionally `extract` two or three for comparison.
+
+## Finish-work retrospective (on demand)
+
+The user explicitly wants to look back at this task — not as a forced step, only when they ask.
+
+- "Summarize what we did in this task."
+- "What were the key decisions / surprises?"
+- "Write up the lessons from this round."
+- "总结一下这次的经验"
+- "记一下这次踩的坑"
+- "复盘下这个任务"
+
+Reach: identify the current task's session id (from `.cviauto/.runtime/sessions/*.json` or `mem list --task <task-dir>`), then `extract <id> --phase brainstorm` and `--phase implement`. Present a summary — surface concrete file:line citations where possible. Whether to also write the summary somewhere (PRD, spec, notes file) is the user's call; offer, don't auto-write.
+
+## Anti-patterns: do NOT reach for `mem` here
+
+- "What does this function do?" → read the file.
+- "Why is this test failing?" → read the test output and the file.
+- "What's the right pattern for X in our codebase?" → grep / read spec files.
+- "What's the latest npm version of Y?" → call `npm view`.
+- "Fix this bug." → debug. Reach for `mem` only if you suspect prior context exists; otherwise it is noise.
+
+The bar stays: would a senior teammate ask "didn't we already talk about this?" before answering? If yes, reach for `mem`. If no, don't.

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: cviauto-spec-bootstrap
+description: "Bootstrap project-specific Cviauto coding specs with a platform-neutral single-agent workflow. Use when creating or refreshing .cviauto/spec guidelines, analyzing a codebase with GitNexus, ABCoder, or source inspection, decomposing package/layer spec work, and writing real codebase-backed spec docs without placeholder text."
+---
+
+# Cviauto Spec Bootstrap
+
+Use this skill to create or refresh `.cviauto/spec/` guidelines from the real codebase. One capable agent owns the full loop: analyze the repository, choose the spec boundaries, write the docs, and verify the result. The workflow does not depend on a specific host, CLI, or agent brand.
+
+## Workflow
+
+1. Confirm Cviauto is initialized and inspect the current `.cviauto/spec/` tree.
+2. Analyze the repository architecture with the best available tools: GitNexus, ABCoder, language tooling, and direct source reads.
+3. Decompose the spec work by package and layer only when that reflects the actual codebase.
+4. Fill or reshape the spec files with concrete patterns, file paths, examples, and anti-patterns from the project.
+5. Verify that the final specs are internally consistent and contain no template placeholders.
+
+## Reference Routing
+
+| Need | Read |
+|------|------|
+| Repository architecture analysis | [references/repository-analysis.md](references/repository-analysis.md) |
+| Spec work decomposition and task planning | [references/spec-task-planning.md](references/spec-task-planning.md) |
+| Writing high-signal Cviauto spec files | [references/spec-writing.md](references/spec-writing.md) |
+| GitNexus and ABCoder MCP setup | [references/mcp-setup.md](references/mcp-setup.md) |
+
+## Operating Rules
+
+- Treat templates as starting points, not contracts. Delete, rename, split, or add spec files when the repository calls for it.
+- Prefer source-backed rules over generic advice. Every important recommendation should point at a real file or repeated local pattern.
+- Keep execution single-owner by default. Optional helper agents are an implementation detail, not a requirement or user-visible dependency.
+- Do not write platform-specific instructions unless the target project already standardizes on that platform.
+- Do not leave placeholder text, empty headings, or copied boilerplate in `.cviauto/spec/`.
+
+## Done Criteria
+
+- `.cviauto/spec/` describes the project as it exists now.
+- Each relevant package or layer has practical coding guidance with real examples.
+- Non-applicable template sections are removed.
+- `index.md` files match the final spec file set.
+- Any required setup or analysis assumptions are documented in the relevant spec or task notes.

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/references/mcp-setup.md

@@ -0,0 +1,90 @@
+# MCP Setup
+
+GitNexus and ABCoder are recommended when bootstrapping Cviauto specs because they expose architecture and AST context to the agent. They are tool choices, not platform requirements. Configure them through whatever MCP mechanism your agent host provides.
+
+## GitNexus
+
+GitNexus builds a code knowledge graph from the repository. Use it for module boundaries, execution flows, dependency relationships, blast radius, and graph queries.
+
+### Install and Index
+
+```bash
+# Run from the repository root.
+npx gitnexus analyze
+
+# Check index status.
+npx gitnexus status
+
+# Re-index after code changes when the analysis is stale.
+npx gitnexus analyze
+```
+
+The index is written to `.gitnexus/`. Keep embeddings only if the project already uses them; otherwise a normal index is enough for spec bootstrapping.
+
+### MCP Server Command
+
+Use this server command in the host's MCP configuration:
+
+```bash
+npx -y gitnexus mcp
+```
+
+### Useful Tools
+
+| Tool | Purpose |
+|------|---------|
+| `gitnexus_query` | Find execution flows and functional areas by concept |
+| `gitnexus_context` | Inspect callers, callees, references, and process participation for a symbol |
+| `gitnexus_impact` | Understand blast radius before changing a symbol |
+| `gitnexus_detect_changes` | Check changed symbols and affected flows before finishing |
+| `gitnexus_cypher` | Run direct graph queries |
+| `gitnexus_list_repos` | List indexed repositories |
+
+## ABCoder
+
+ABCoder parses code into UniAST and gives precise package, file, and node-level structure. Use it for signatures, type shapes, implementations, dependencies, and reverse references.
+
+### Install
+
+```bash
+go install github.com/cloudwego/abcoder@latest
+abcoder --help
+```
+
+### Parse Repositories
+
+```bash
+abcoder parse /absolute/path/to/package \
+  --lang typescript \
+  --name package-name \
+  --output ~/abcoder-asts
+```
+
+For monorepos, parse each package with a stable `--name` so task notes can reference the same repository names.
+
+### MCP Server Command
+
+Use this server command in the host's MCP configuration:
+
+```bash
+abcoder mcp ~/abcoder-asts
+```
+
+### Useful Tools
+
+| Tool | Layer | Purpose |
+|------|-------|---------|
+| `list_repos` | 1 | List parsed repositories |
+| `get_repo_structure` | 2 | Inspect packages and files |
+| `get_package_structure` | 3 | Inspect nodes within a package |
+| `get_file_structure` | 3 | Inspect functions, classes, types, and signatures in a file |
+| `get_ast_node` | 4 | Retrieve code, dependencies, references, and implementations |
+
+## Verification
+
+After configuration, verify from the agent host that both MCP servers are visible. Then run one simple query against each server before starting the spec writing pass.
+
+```bash
+ls .gitnexus/meta.json
+ls ~/abcoder-asts/*.json
+```

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/references/repository-analysis.md

@@ -0,0 +1,59 @@
+# Repository Analysis
+
+The goal is to discover the project's real architecture before writing rules. Do not start from generic spec templates and fill blanks. Start from the code, then let the spec structure follow.
+
+## Analysis Order
+
+1. Read the existing `.cviauto/spec/` tree and note which files are templates, outdated, or already project-specific.
+2. Inspect package manifests, build scripts, workspace config, and top-level documentation to identify packages and runtime layers.
+3. Use GitNexus for execution flows, module clusters, dependency hubs, and impact-sensitive areas.
+4. Use ABCoder or language-native tooling for exact signatures, types, class boundaries, and implementation examples.
+5. Read representative source and test files directly before turning any finding into a spec rule.
+
+## What To Capture
+
+| Area | Questions |
+|------|-----------|
+| Package boundaries | What does each package own? What imports cross boundaries? |
+| Runtime layers | Which code is CLI, backend, frontend, worker, shared library, test-only, or tooling? |
+| Core abstractions | Which types, services, stores, commands, routes, or adapters define the system shape? |
+| Data flow | Where does user input enter, how is it validated, and where does state persist? |
+| Error handling | How are failures represented, logged, surfaced, and tested? |
+| Configuration | Where do defaults, environment config, generated files, and templates live? |
+| Tests | Which test styles are trusted examples for new work? |
+
+## GitNexus Usage
+
+Start broad, then inspect specific symbols:
+
+```text
+gitnexus_query({query: "CLI command execution flow"})
+gitnexus_query({query: "template generation and migration"})
+gitnexus_context({name: "SymbolName"})
+gitnexus_cypher({query: "MATCH (n)-[r]->(m) RETURN n.name, type(r), m.name LIMIT 30"})
+```
+
+Use GitNexus results to find important files and flows. Do not quote graph output as the final authority until you have checked the relevant source files.
+
+## ABCoder Usage
+
+Use ABCoder when the spec needs exact code shapes:
+
+```text
+list_repos()
+get_repo_structure({repo_name: "package-name"})
+get_file_structure({repo_name: "package-name", file_path: "src/example.ts"})
+get_ast_node({repo_name: "package-name", node_ids: [{mod_path: "...", pkg_path: "...", name: "SymbolName"}]})
+```
+
+ABCoder is most valuable for documenting constructor patterns, function signatures, type contracts, and reference chains.
+
+## Analysis Notes
+
+Keep short notes while analyzing. The notes should include:
+
+- Package or layer name.
+- Files that define the local pattern.
+- Rules the spec should teach.
+- Anti-patterns found in old code, comments, tests, or migration paths.
+- Spec files that should be created, deleted, renamed, or merged.

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/references/spec-task-planning.md

@@ -0,0 +1,61 @@
+# Spec Task Planning
+
+Use a single agent as the default execution model. The agent may create Cviauto tasks for traceability, but the skill should not require a specific platform, CLI, or parallel worker model.
+
+## Decomposition
+
+Create spec work units around real ownership boundaries:
+
+- One package when a package has its own conventions.
+- One layer when the same package has distinct frontend, backend, CLI, worker, or shared-library rules.
+- One cross-cutting guide when a pattern spans packages and is not owned by one layer.
+
+Avoid artificial decomposition. A small library usually needs one focused spec pass, not several tasks.
+
+## Task Shape
+
+When a Cviauto task is useful, write a concise PRD with these sections:
+
+```markdown
+# Fill <package-or-layer> Cviauto Specs
+
+## Goal
+Write project-specific `.cviauto/spec/` guidance for <scope>.
+
+## Scope
+- Spec directory:
+- Source directories to inspect:
+- Tests to inspect:
+- Out of scope:
+
+## Architecture Context
+Summarize the concrete findings from repository analysis.
+
+## Files To Create Or Update
+- `.cviauto/spec/.../index.md`
+- `.cviauto/spec/.../<topic>.md`
+
+## Rules
+- Adapt the spec file set to the real codebase.
+- Use real source examples with file paths.
+- Remove template-only sections that do not apply.
+- Do not modify product source code unless the task explicitly asks for it.
+
+## Acceptance Criteria
+- [ ] Specs contain concrete examples and anti-patterns from the repository.
+- [ ] No placeholder text remains.
+- [ ] Index files match the final spec files.
+- [ ] Claims are backed by source files, tests, or project docs.
+```
+
+## Optional Helper Agents
+
+If the host supports subagents, helpers can inspect independent packages or run verification. They are optional. The main agent still owns integration and final quality.
+
+Helper tasks must have clear ownership:
+
+- Read-only research tasks may inspect any source needed for the assigned scope.
+- Write tasks should own disjoint spec directories.
+- Verification tasks should check placeholder removal, broken links, and consistency.
+
+Do not encode helper-agent names, vendor-specific commands, or platform-specific routing in the skill. Put only the required work and acceptance criteria in the task.

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/references/spec-writing.md

@@ -0,0 +1,70 @@
+# Spec Writing
+
+Cviauto specs are coding guidance for future agents. They should explain how to work in this repository, not how a generic project might be organized.
+
+## Write From Evidence
+
+Each important rule should be backed by one of these:
+
+- A source file that demonstrates the preferred pattern.
+- A test file that shows expected behavior.
+- A project document that defines the convention.
+- A repeated pattern across multiple files.
+
+Use short snippets only when they make the rule clearer. Prefer linking to the file path and naming the symbol or behavior.
+
+## File Structure
+
+Keep the spec tree aligned with the project:
+
+- Keep `index.md` as the navigation file for the spec directory.
+- Split topics when developers would look for them independently.
+- Merge topics when separate files would repeat the same rule.
+- Delete template files that do not apply.
+- Add new files for important local patterns the template missed.
+
+## Content Standards
+
+Good spec sections include:
+
+- When the rule applies.
+- The local pattern to follow.
+- The source or test files that prove the pattern.
+- Common mistakes or anti-patterns.
+- Verification commands or checks when they are specific and reliable.
+
+Avoid:
+
+- Placeholder prose.
+- Generic framework advice.
+- Tool instructions that only work in one agent host.
+- Long copied code blocks.
+- Rules based on a single accidental implementation detail.
+
+## Example Shape
+
+```markdown
+## Command Handlers
+
+Command handlers should keep argument parsing, validation, and side effects separate. The local pattern is:
+
+- Parse CLI flags at the command boundary.
+- Convert raw inputs into typed task options before invoking core logic.
+- Keep filesystem writes in the command or service layer, not in template helpers.
+
+Reference files:
+- `packages/cli/src/commands/example.ts`
+- `packages/cli/test/commands/example.test.ts`
+
+Avoid passing raw `process.argv` or unvalidated config objects into shared helpers.
+```
+
+## Final Pass
+
+Before finishing:
+
+```bash
+grep -R "To be filled\\|TODO: fill\\|placeholder" .cviauto/spec
+```
+
+Also check links, index files, and whether any spec still describes a template rather than this repository.