@ibotor/smart-trellis 0.5.19

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

@@ -0,0 +1,79 @@
+# Agents
+
+Trellis agent files define specialized roles. Common Trellis agents in a user project are:
+
+- `trellis-research`
+- `trellis-implement`
+- `trellis-check`
+
+File locations and formats differ by platform, but responsibility boundaries should stay consistent.
+
+## Agent Responsibilities
+
+| Agent | Responsibility |
+| --- | --- |
+| `trellis-research` | Investigate the question and write findings into the current task's `research/`. |
+| `trellis-implement` | Implement against `prd.md`, `info.md`, `implement.jsonl`, and related spec/research. |
+| `trellis-check` | Review changes, fix discovered issues, and run necessary checks. |
+
+Agent files should not become generic chat prompts. They should define input sources, write boundaries, whether code may be changed, and how results are reported.
+
+## Common Paths
+
+| Platform | Agent path |
+| --- | --- |
+| Claude Code | `.claude/agents/trellis-*.md` |
+| Cursor | `.cursor/agents/trellis-*.md` |
+| OpenCode | `.opencode/agents/trellis-*.md` |
+| Codex | `.codex/agents/trellis-*.toml` |
+| Kiro | `.kiro/agents/trellis-*.json` |
+| Gemini CLI | `.gemini/agents/trellis-*.md` |
+| Qoder | `.qoder/agents/trellis-*.md` |
+| CodeBuddy | `.codebuddy/agents/trellis-*.md` |
+| Factory Droid | `.factory/droids/trellis-*.md` |
+| Pi Agent | `.pi/agents/trellis-*.md` |
+
+GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project.
+
+Main-session workflow platforms such as Kilo, Antigravity, and Windsurf may not have Trellis sub-agent files. They usually rely on workflows/skills to guide the main session.
+
+## Two Context Loading Modes
+
+### hook push
+
+The platform hook injects task context before the agent starts. The agent file itself can focus more on responsibilities and boundaries.
+
+Common on platforms that support agent hooks.
+
+### agent pull
+
+The agent file instructs the agent to read after startup:
+
+- `python3 ./.trellis/scripts/task.py current --source`
+- current task `prd.md`
+- `info.md`
+- `implement.jsonl` or `check.jsonl`
+- spec/research files referenced by JSONL
+
+This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| Implement agent must follow extra restrictions | The platform's `trellis-implement` agent file. |
+| Check agent must run project-specific commands | `trellis-check` agent file, and `.trellis/spec/` if needed. |
+| Research agent must output a fixed format | `trellis-research` agent file. |
+| Agent cannot read task context | Agent prelude or `inject-subagent-context` hook. |
+| Add a project-specific agent | Platform agent directory + related workflow/command/skill entry point. |
+
+## Modification Principles
+
+1. **Keep responsibilities single-purpose**. Do not mix research, implement, and check responsibilities into one agent.
+2. **Specify the read order**. Agents must know to start from the active task and then find the PRD and JSONL.
+3. **Specify write boundaries**. Research usually only writes `research/`; implement can write code; check can fix issues.
+4. **Keep semantics synchronized in multi-platform projects**. If the user configured Claude, Codex, and Cursor together, decide whether changes to one platform's agent also need to be applied to others.
+
+## Do Not Default To Editing Upstream Templates
+
+Local AI should default to modifying platform agent files inside the user project. Discuss upstream template source only when the user explicitly wants to contribute the change back to Trellis.

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

@@ -0,0 +1,69 @@
+# Hooks And Settings
+
+Hooks/settings are the entry layer that connects a platform to Trellis. They decide which scripts, plugins, or extensions a platform runs for which events.
+
+## Settings Responsibilities
+
+settings/config files usually register:
+
+- session-start hook: injects a Trellis overview when a new session starts or context resets.
+- workflow-state hook: parses `[workflow-state:STATUS]` blocks from `.trellis/workflow.md` and emits the body matching the current task `status` on each user input. Parser-only; the script does not embed fallback content.
+- sub-agent context hook: injects task context when implementation/check/research agents start.
+- shell/session bridge: lets shell commands see the same Trellis session identity.
+- platform plugin or extension entry points.
+
+Common files:
+
+| Platform | settings/config |
+| --- | --- |
+| Claude Code | `.claude/settings.json` |
+| Cursor | `.cursor/hooks.json` |
+| Codex | `.codex/hooks.json`, `.codex/config.toml` |
+| OpenCode | `.opencode/package.json`, `.opencode/plugins/*` |
+| Kiro | `.kiro/hooks/` + platform config |
+| Gemini CLI | `.gemini/settings.json` |
+| Qoder | `.qoder/settings.json` |
+| CodeBuddy | `.codebuddy/settings.json` |
+| GitHub Copilot | `.github/copilot/hooks.json` |
+| Factory Droid | `.factory/settings.json` |
+| Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` |
+
+Whether these files exist in a project depends on which `trellis init --<platform>` flags the user ran.
+
+## Hook Script Types
+
+| Script | Purpose |
+| --- | --- |
+| `session-start.py` | Generates session-start context. |
+| `inject-workflow-state.py` | Parses `[workflow-state:STATUS]` blocks in `.trellis/workflow.md` and emits the body matching the current task status. Falls back to `Refer to workflow.md for current step.` when no matching block exists. |
+| `inject-subagent-context.py` | Injects PRD, JSONL context, and related spec/research into sub-agents. |
+| `inject-shell-session-context.py` | Lets shell commands inherit Trellis session identity. |
+
+Not every platform has every hook. Do not copy files from another platform just because a platform lacks a hook; first confirm whether that platform supports the corresponding event.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| AI should see more/less context in a new session | Platform `session-start` hook. |
+| Per-turn hint policy should change | `[workflow-state:STATUS]` block in `.trellis/workflow.md`. The hook parses workflow.md verbatim — no script edit required. |
+| Sub-agent cannot read PRD/spec | `inject-subagent-context` hook or agent prelude. |
+| `task.py current` in shell has no active task | Shell/session bridge hook or platform environment variable configuration. |
+| Disable an automatic injection | The corresponding hook registration in settings/config. |
+
+## Modification Principles
+
+1. **Settings wire things up; hooks define behavior**. If only the hook changes, the platform may never call it. If only settings change, behavior may not change.
+2. **Confirm platform event names first**. Different platforms use different names for SessionStart, UserPromptSubmit, AgentSpawn, shell execution, and similar events.
+3. **Hooks read local `.trellis/`, not upstream source**. `.trellis/scripts/` and `.trellis/workflow.md` in the user project are the default targets.
+4. **Errors must be visible**. Hook failures should tell the user what was not injected instead of silently leaving the AI without context.
+
+## Troubleshooting Path
+
+If the user says "AI did not read Trellis state":
+
+1. Check whether the platform settings register the hook.
+2. Check whether the hook file exists.
+3. Manually run the `.trellis/scripts/get_context.py` or `task.py current --source` command that the hook depends on.
+4. Check whether active task state exists in `.trellis/.runtime/sessions/`.
+5. Check whether the platform shell passes session identity.

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

@@ -0,0 +1,59 @@
+# Platform Files Overview
+
+Trellis connects the same local architecture to different AI tools. `.trellis/` stores the shared runtime; platform directories store adapter files that define how each AI tool enters Trellis.
+
+When a local AI modifies Trellis, it should distinguish two file categories first:
+
+- **Shared files**: `.trellis/workflow.md`, `.trellis/tasks/`, `.trellis/spec/`, `.trellis/scripts/`.
+- **Platform files**: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
+
+Platform files do not store business state. They let the corresponding AI tool read Trellis state, call Trellis scripts, and load Trellis skills/agents/hooks.
+
+## Platform File Categories
+
+| Category | Common paths | Purpose |
+| --- | --- | --- |
+| settings/config | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json` | Register hooks, plugins, extensions, or platform behavior. |
+| hooks/plugins/extensions | `.claude/hooks/`, `.opencode/plugins/`, `.pi/extensions/` | Inject context at session start, user input, agent startup, shell execution, and similar events. |
+| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/` | Define `trellis-research`, `trellis-implement`, and `trellis-check`. |
+| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Capability descriptions that auto-trigger or can be read on demand. |
+| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.windsurf/workflows/` | Entry points explicitly invoked by the user. |
+
+## Three Platform Integration Modes
+
+### 1. Hook / Extension Driven
+
+These platforms can trigger scripts or plugins on specific events and actively inject Trellis context into AI.
+
+Common capabilities:
+
+- session-start injection of a `.trellis/` overview.
+- workflow-state hints for each user turn.
+- PRD/spec/research injection when sub-agents start.
+- Shell commands inheriting session identity.
+
+To change "when the AI knows what," inspect hooks/plugins/extensions and settings first.
+
+### 2. Agent Prelude / Pull-Based
+
+Some platforms cannot reliably let hooks rewrite sub-agent prompts, so the agent file itself instructs the agent to read the active task, PRD, and JSONL context after startup.
+
+To change how sub-agents load context, inspect the agent files themselves.
+
+### 3. Main-Session Workflow
+
+Some platforms do not have Trellis sub-agent or hook capabilities. They rely on workflows/skills/commands to guide the main-session AI to read files, run scripts, and move tasks forward.
+
+To change behavior, inspect platform workflows/skills/commands and `.trellis/workflow.md`.
+
+## Local Modification Order
+
+When the user asks to customize behavior for a platform, the AI should inspect files in this order:
+
+1. Read `.trellis/workflow.md` to confirm the shared flow.
+2. Read the target platform's settings/config to see which hooks/agents/skills/commands are registered.
+3. Read the target platform's agents/skills/commands/hooks.
+4. Modify the local file closest to the user's need.
+5. If the change affects the shared flow, synchronize `.trellis/workflow.md` or `.trellis/spec/`.
+
+Do not modify only platform files and forget the shared workflow. Do not modify only `.trellis/workflow.md` and forget that platform entry points may still contain old descriptions.

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

@@ -0,0 +1,74 @@
+# Platform File Map
+
+This page lists common Trellis file locations in a user project by platform. Whether a platform directory exists in an actual project depends on which `trellis init --<platform>` commands the user ran.
+
+## Matrix
+
+| Platform | CLI flag | Main directory | Skill directory | Agent directory | Hooks/extensions |
+| --- | --- | --- | --- | --- | --- |
+| Claude Code | `--claude` | `.claude/` | `.claude/skills/` | `.claude/agents/` | `.claude/hooks/` + `.claude/settings.json` |
+| Cursor | `--cursor` | `.cursor/` | `.cursor/skills/` | `.cursor/agents/` | `.cursor/hooks.json` + `.cursor/hooks/` |
+| OpenCode | `--opencode` | `.opencode/` | `.opencode/skills/` | `.opencode/agents/` | `.opencode/plugins/` |
+| Codex | `--codex` | `.codex/` | `.agents/skills/` | `.codex/agents/` | `.codex/hooks/` + `.codex/hooks.json` |
+| Kilo | `--kilo` | `.kilocode/` | `.kilocode/skills/` | Usually none | `.kilocode/workflows/` |
+| Kiro | `--kiro` | `.kiro/` | `.kiro/skills/` | `.kiro/agents/` | `.kiro/hooks/` |
+| Gemini CLI | `--gemini` | `.gemini/` | `.agents/skills/` | `.gemini/agents/` | `.gemini/settings.json` + `.gemini/hooks/` |
+| Antigravity | `--antigravity` | `.agent/` | `.agent/skills/` | Usually none | `.agent/workflows/` |
+| Windsurf | `--windsurf` | `.windsurf/` | `.windsurf/skills/` | Usually none | `.windsurf/workflows/` |
+| Qoder | `--qoder` | `.qoder/` | `.qoder/skills/` | `.qoder/agents/` | `.qoder/hooks/` + `.qoder/settings.json` |
+| CodeBuddy | `--codebuddy` | `.codebuddy/` | `.codebuddy/skills/` | `.codebuddy/agents/` | `.codebuddy/hooks/` + `.codebuddy/settings.json` |
+| GitHub Copilot | `--copilot` | `.github/` | `.github/skills/` | `.github/agents/` | `.github/copilot/hooks/` + prompts |
+| Factory Droid | `--droid` | `.factory/` | `.factory/skills/` | `.factory/droids/` | `.factory/hooks/` + settings |
+| Pi Agent | `--pi` | `.pi/` | `.pi/skills/` | `.pi/agents/` | `.pi/extensions/trellis/` + `.pi/settings.json` |
+
+## Capability Groups
+
+### Trellis Sub-Agent Support
+
+These platforms usually have `trellis-research`, `trellis-implement`, and `trellis-check` files:
+
+- Claude Code
+- Cursor
+- OpenCode
+- Codex
+- Kiro
+- Gemini CLI
+- Qoder
+- CodeBuddy
+- GitHub Copilot
+- Factory Droid
+- Pi Agent
+
+When changing implementation/check/research behavior, look for the corresponding platform agent files first.
+
+### Main-Session Workflow Platforms
+
+These platforms rely more on workflows/skills to guide the main session:
+
+- Kilo
+- Antigravity
+- Windsurf
+
+When changing behavior, inspect workflows and skills first. Do not assume Trellis sub-agents exist.
+
+### Shared `.agents/skills/`
+
+Codex writes the shared `.agents/skills/` layer. Some tools that support agentskills.io can also read this directory. If the user wants multiple compatible tools to share one skill, consider `.agents/skills/` first, but do not assume every platform reads it.
+
+## Decision Rules When Modifying Platform Files
+
+1. User specified a platform: modify only that platform directory unless shared workflow/spec files must also change.
+2. User says "all platforms should do this": synchronize equivalent entry points platform by platform; do not modify only one directory.
+3. User only says "my AI": inspect the configuration directories that actually exist in the project and infer the current AI platform.
+4. User wants project rules: prefer `.trellis/spec/` or a project-local skill.
+5. User wants Trellis behavior: edit `.trellis/workflow.md` plus platform hooks/agents/skills/commands.
+
+## When Paths Differ
+
+Platform ecosystems change, and user projects may already be customized. If this table disagrees with local files, use the actual settings/config in the user project as authoritative:
+
+- Check the hook that settings registers.
+- Check the script that a command/prompt/workflow points to.
+- Judge behavior by the read rules currently written in the agent file.
+
+Do not delete a custom file just because it is not listed in this path table.

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

@@ -0,0 +1,83 @@
+# Skills, Commands, Prompts, And Workflows
+
+Skills and commands are textual entry points for user interaction with Trellis. Different platforms use different names, but their core purpose is the same: tell the AI how to enter the Trellis 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. |
+
+Trellis workflow skills usually share one semantic set: brainstorm, before-dev, check, update-spec, break-loop. Multi-file built-in skills such as `trellis-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/` |
+| Windsurf | `.windsurf/skills/`, `.windsurf/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/` |
+
+In a user project, use the files actually generated by init as authoritative.
+
+## Skill Structure
+
+A common skill is a directory:
+
+```text
+trellis-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 `.trellis/` files to read.
+- Which scripts to run.
+- How to report after completion.
+
+They should not store task state; task state belongs in `.trellis/tasks/` and `.trellis/.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 `trellis-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 `trellis-meta`.
+
+If the user only wants local AI to know one more project rule, usually create a project-local skill or update `.trellis/spec/` instead of changing a Trellis built-in workflow skill.

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

@@ -0,0 +1,41 @@
+---
+name: trellis-spec-bootstarp
+description: "Bootstrap project-specific Trellis coding specs with a platform-neutral single-agent workflow. Use when creating or refreshing .trellis/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."
+---
+
+# Trellis Spec Bootstarp
+
+Use this skill to create or refresh `.trellis/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 Trellis is initialized and inspect the current `.trellis/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 Trellis 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 `.trellis/spec/`.
+
+## Done Criteria
+
+- `.trellis/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-bootstarp/references/mcp-setup.md

@@ -0,0 +1,90 @@
+# MCP Setup
+
+GitNexus and ABCoder are recommended when bootstrapping Trellis 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-bootstarp/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 `.trellis/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-bootstarp/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 Trellis 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 Trellis task is useful, write a concise PRD with these sections:
+
+```markdown
+# Fill <package-or-layer> Trellis Specs
+
+## Goal
+Write project-specific `.trellis/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
+- `.trellis/spec/.../index.md`
+- `.trellis/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.