@blxzer/cursor-trellis 0.1.0

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

@@ -0,0 +1,76 @@
+# 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.
+
+This fork's first-class platform surfaces are Claude Code, Codex, and Cursor. Other rows are legacy adapters: keep them working when explicitly configured, but do not treat them as equal targets for new framework/runtime behavior without a compatibility pass.
+
+## Matrix
+
+| Platform | Tier | CLI flag | Main directory | Skill directory | Agent directory | Hooks/extensions |
+| --- | --- | --- | --- | --- | --- | --- |
+| Claude Code | First-class | `--claude` | `.claude/` | `.claude/skills/` | `.claude/agents/` | `.claude/hooks/` + `.claude/settings.json` |
+| Cursor | First-class | `--cursor` | `.cursor/` | `.cursor/skills/` | `.cursor/agents/` | `.cursor/hooks.json` + `.cursor/hooks/` |
+| Codex | First-class | `--codex` | `.codex/` | `.agents/skills/` | `.codex/agents/` | `.codex/hooks/` + `.codex/hooks.json` |
+| OpenCode | Legacy adapter | `--opencode` | `.opencode/` | `.opencode/skills/` | `.opencode/agents/` | `.opencode/plugins/` |
+| Kilo | Legacy adapter | `--kilo` | `.kilocode/` | `.kilocode/skills/` | Usually none | `.kilocode/workflows/` |
+| Kiro | Legacy adapter | `--kiro` | `.kiro/` | `.kiro/skills/` | `.kiro/agents/` | `.kiro/hooks/` |
+| Gemini CLI | Legacy adapter | `--gemini` | `.gemini/` | `.agents/skills/` | `.gemini/agents/` | `.gemini/settings.json` + `.gemini/hooks/` |
+| Antigravity | Legacy adapter | `--antigravity` | `.agent/` | `.agent/skills/` | Usually none | `.agent/workflows/` |
+| Windsurf | Legacy adapter | `--windsurf` | `.windsurf/` | `.windsurf/skills/` | Usually none | `.windsurf/workflows/` |
+| Qoder | Legacy adapter | `--qoder` | `.qoder/` | `.qoder/skills/` | `.qoder/agents/` | `.qoder/hooks/` + `.qoder/settings.json` |
+| CodeBuddy | Legacy adapter | `--codebuddy` | `.codebuddy/` | `.codebuddy/skills/` | `.codebuddy/agents/` | `.codebuddy/hooks/` + `.codebuddy/settings.json` |
+| GitHub Copilot | Legacy adapter | `--copilot` | `.github/` | `.github/skills/` | `.github/agents/` | `.github/copilot/hooks/` + prompts |
+| Factory Droid | Legacy adapter | `--droid` | `.factory/` | `.factory/skills/` | `.factory/droids/` | `.factory/hooks/` + settings |
+| Pi Agent | Legacy adapter | `--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,128 @@
+# 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 has two skill families:
+
+- Workflow skills: `brainstorm`, `before-dev`, `check`, `update-spec`, and `break-loop`.
+- Multi-file bundled skills include `trellis-meta`, `trellis-spec-bootstrap`, `trellis-skill-creator`, `smart-search-cli`, `trellis-micro-grill`, and `trellis-cursor2plus-setup`.
+
+Bundled skills are installed as directories and may include nested `agents/`, `examples/`, `references/`, or other lazy-loadable files. Do not describe bundled skills as a closed `trellis-*` list: `smart-search-cli` intentionally keeps its existing non-`trellis-` name.
+
+`smart-search-cli` is CLI-backed source retrieval. The Trellis package exposes the `smart-search` executable through its runtime wrapper; the skill documents how agents should use that CLI and cite retrieved sources.
+
+`trellis-spec-bootstrap` bootstraps project-specific `.trellis/spec/` guidance from the real repository.
+
+`trellis-skill-creator` is the authoring and review guide for Trellis-compatible skills. Use it when creating or improving project-local skills, shared `.agents/skills/`, platform-specific skill directories, or upstream bundled skills. Keep `trellis-meta` focused on architecture and routing.
+
+`trellis-micro-grill` is the Trellis clarification adapter. It asks one high-value question at a time and escalates to Lite, Full, or Parent/Child task modes only when durable artifacts or broader risk require it.
+
+`trellis-cursor2plus-setup` guides Cursor++ BYOK users through `trellis-task-models.json5` (primary/fallback per Task role), `patch_wpelc8.py`, and Reload Window. Use after `trellis init` with Cursor or when `providers.json` changes.
+
+## Common Paths
+
+| Platform | Common entries |
+| --- | --- |
+| Claude Code | `.claude/skills/`, `.claude/commands/` |
+| Cursor | `.cursor/skills/` (preferred); `.cursor/commands/` is legacy compatibility-only |
+| 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.
+On current Cursor, Trellis prefers Agent Skills for manual entrypoints such as
+`trellis-continue` and `trellis-finish-work`; legacy `.cursor/commands` files
+may exist in older projects but should be treated as an explicit compatibility
+surface rather than the default current-platform command surface.
+
+## Skill Structure
+
+A common skill is a directory:
+
+```text
+trellis-meta/
+├── SKILL.md
+└── references/
+trellis-spec-bootstrap/
+├── SKILL.md
+└── references/
+trellis-skill-creator/
+├── SKILL.md
+└── references/
+smart-search-cli/
+├── SKILL.md
+├── agents/
+├── examples/
+└── references/
+trellis-micro-grill/
+└── SKILL.md
+trellis-cursor2plus-setup/
+└── SKILL.md
+```
+
+`SKILL.md` should tell the AI:
+
+- When to use this skill.
+- Which reference to read first for the selected 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/`.
+
+Task selection uses `selected_task`, not legacy current/active task commands. The current command chain is:
+
+- `task.py dashboard` for routing without selecting a task.
+- `task.py select <task>` to select a task for the live session without changing `task.status`.
+- `task.py selected [--source]` to inspect the live-session selection.
+- `task.py start-execution <task> --check` and then `--approved` for the execution boundary.
+- `task.py exit` to clear the live-session selection without changing `task.status`.
+- `task.py archive <task>` for guarded completion.
+
+Do not reintroduce `task.py start`, `task.py current`, or `task.py finish` into platform commands or docs.
+
+## 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; on current Cursor, prefer `.cursor/skills/trellis-continue` and `.cursor/skills/trellis-finish-work` over legacy `.cursor/commands`. |
+
+## Modification Principles
+
+1. **Keep entry files short; references carry long content**. This matters especially for multi-file skills like `trellis-meta` and `trellis-skill-creator`.
+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-micro-grill/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: trellis-micro-grill
+description: "Clarifies small underspecified Trellis requests with one high-value question at a time before direct execution. Use when a request is likely small, missing details would materially change the result, and creating a Trellis task would be premature."
+---
+
+# Trellis Micro-Grill
+
+## Goal
+
+Clarify a small request just enough to execute it directly without creating Trellis task artifacts by default.
+
+## Hard Constraints
+
+- Always ask exactly one high-value question at a time.
+- Always inspect local files first when the missing answer is discoverable from the project.
+- Always include a recommended answer when enough evidence exists.
+- Always use Simplified Chinese for user-facing questions.
+- Never create Trellis task artifacts by default.
+- Never keep grilling after the request is clear enough to execute.
+- Never repeat already answered questions after escalation.
+
+## Workflow
+
+1. Confirm internally that the request is small, underspecified, and not already covered by a selected Trellis task.
+2. Inspect relevant local context first if it can answer the missing detail.
+3. Ask one question whose answer would most change the result.
+4. Include a recommended answer with the concrete tradeoff.
+5. After the user answers, summarize the clarified requirement in one or two Chinese sentences.
+6. Execute directly once the requirement is clear enough.
+
+## Escalation
+
+Escalate once when the clarified work no longer fits Micro-Grill:
+
+- Use Lite Task when there is one independently verifiable deliverable that needs persistence, review, or continuation.
+- Use Full Task when one deliverable has broad impact, platform-adapter changes, external research dependency, or durable design risk.
+- Use Parent/Child when there are multiple independently verifiable deliverables, staged execution, parallel execution, or Parent-controlled integration needs.
+
+When escalating, hand the clarified answers into `trellis-brainstorm` and update Trellis artifacts there.
+
+## When NOT to Use
+
+- Do not use for multi-deliverable work.
+- Do not use for cross-platform workflow changes.
+- Do not use for risky refactors, migrations, prompt deployments, or durable architecture decisions.
+- Do not use when the request is already clear enough to execute.
+- Do not use when there is already a selected Trellis task for the work.

package/dist/templates/common/bundled-skills/trellis-skill-creator/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: trellis-skill-creator
+description: "Create or improve Trellis-compatible agent skills. Use when the user asks to author a project-local skill, shared .agents skill, platform-specific skill, or upstream Trellis bundled skill."
+---
+
+# Trellis Skill Creator
+
+Create high-quality skills for Trellis-managed projects and Trellis bundled templates.
+
+This skill is the authoring and review guide for skill files. It is not the local Trellis architecture map. Use `trellis-meta` first when the user needs to understand or customize `.trellis/`, hooks, settings, commands, prompts, workflows, agents, or platform directory layout.
+
+## Hard Constraints
+
+- Always inspect existing skill directories and platform conventions before creating or changing a skill.
+- Always keep `SKILL.md` short, English-language, and focused on trigger, constraints, workflow, references, and boundaries.
+- Always use lowercase letters, numbers, and hyphens in the frontmatter `name`.
+- Always write a trigger-rich frontmatter `description` that states what the skill does and when it should trigger.
+- Always place safety, sequencing, and reliability rules in a `## Hard Constraints` section before `## Workflow`.
+- Always move long guidance, examples, prompts, and reference material into directly linked files.
+- Always make helper scripts deterministic, runnable from the skill directory, and explicit about inputs and outputs.
+- Never duplicate `trellis-meta` architecture guidance or project-private conventions inside a public Trellis skill.
+- Never edit Cursor's built-in `create-skill`; create or update Trellis-compatible skill files instead.
+
+## Workflow
+
+1. Classify the target skill location and read `references/trellis-skill-locations.md`.
+2. Gather the skill purpose, trigger scenarios, target users, required tools, output shape, and existing local patterns.
+3. Draft or revise `SKILL.md` using `references/authoring-rules.md`.
+4. Add `references/`, `examples/`, `prompts/`, or `scripts/` only when they reduce entry-file size or make execution more deterministic.
+5. Verify the result with `references/review-checklist.md`.
+6. Report changed files, validation performed, and any boundaries or follow-up work.
+
+## References
+
+- `references/trellis-skill-locations.md`: Choose project-local, shared, platform-specific, or upstream bundled skill locations.
+- `references/authoring-rules.md`: Frontmatter, trigger descriptions, hard constraints, progressive disclosure, deterministic scripts, and anti-patterns.
+- `references/review-checklist.md`: Final quality checklist before handing off a skill change.
+
+## When NOT To Use
+
+- Do not use for general Trellis architecture discovery; use `trellis-meta`.
+- Do not use for project coding conventions that belong in `.trellis/spec/`.
+- Do not use for one-off commands or prompts unless the user wants a durable auto-triggered capability.
+- Do not use for non-Trellis global skill installation or platform configuration unless the user explicitly asks for that scope.

package/dist/templates/common/bundled-skills/trellis-skill-creator/references/authoring-rules.md

@@ -0,0 +1,97 @@
+# Skill Authoring Rules
+
+Use these rules when creating or reviewing a Trellis-compatible skill.
+
+## Required Shape
+
+Every active skill directory needs a `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: skill-name
+description: Specific capability and trigger scenarios.
+---
+```
+
+Rules:
+
+- Use lowercase letters, numbers, and hyphens in `name`.
+- Write `description` in third person because platforms inject it into tool or skill discovery prompts.
+- Include both what the skill does and when it should trigger.
+- Keep `SKILL.md` under 500 lines and usually far shorter.
+- Keep `SKILL.md` in English unless the target platform or user explicitly requires another language.
+
+## Description Quality
+
+The description is the trigger surface. It should contain concrete task nouns and user-intent phrases.
+
+Good:
+
+```yaml
+description: "Create or improve Trellis-compatible agent skills. Use when the user asks to author a project-local skill, shared .agents skill, platform-specific skill, or upstream Trellis bundled skill."
+```
+
+Avoid:
+
+```yaml
+description: "Helps with skills."
+```
+
+Checklist:
+
+- Names the capability.
+- Names common trigger situations.
+- Avoids first person.
+- Avoids broad utility wording such as "helper", "tools", or "useful".
+- Does not claim support for platforms or files the skill does not cover.
+
+## Hard Constraints
+
+Put a `## Hard Constraints` section near the top, before `## Workflow`, when the skill has safety, sequencing, scope, or reliability rules.
+
+Write constraints as imperative one-liners:
+
+- Always inspect local files before editing.
+- Never modify global configuration without explicit user approval.
+- Always run the validator before final output.
+
+Do not bury constraints in paragraphs. Do not repeat the same rule in another section; make Hard Constraints the single source of truth.
+
+## Progressive Disclosure
+
+`SKILL.md` should route, not carry every detail.
+
+Good candidates for references:
+
+- Detailed authoring rules.
+- Domain background.
+- Long examples.
+- Output templates.
+- Platform-specific notes.
+- Review checklists.
+
+Keep references one level deep and link them directly from `SKILL.md`. Avoid reference chains where one reference requires reading another reference before it is useful.
+
+## Deterministic Scripts
+
+Add scripts only when they make the skill more reliable than generated ad hoc code.
+
+Script rules:
+
+- Put scripts under the owning skill directory, usually `scripts/`.
+- Expose only parameters the agent must supply.
+- Let the script decide internal paths, timestamps, defaults, and output filenames when possible.
+- Return structured JSON to stdout when the script mutates files or produces machine-readable status.
+- State whether the agent should execute the script or read it as reference.
+- Avoid shell variables or cross-step state that would not survive separate tool calls.
+
+## Common Anti-Patterns
+
+- Vague frontmatter descriptions that can trigger on unrelated work.
+- A single skill that mixes unrelated workflows.
+- `SKILL.md` files that paste long prompts or full scripts instead of linking references.
+- Rules repeated in several sections with slightly different wording.
+- Missing stop conditions for broad search or expensive loops.
+- Commands that rely on shell variables set by a previous tool call.
+- References to files, scripts, or examples that do not exist.
+- Project-private conventions added to public Trellis bundled skills.

package/dist/templates/common/bundled-skills/trellis-skill-creator/references/review-checklist.md

@@ -0,0 +1,47 @@
+# Skill Review Checklist
+
+Use this checklist before handing off a new or modified skill.
+
+## Frontmatter
+
+- [ ] `name` uses lowercase letters, numbers, and hyphens only.
+- [ ] `description` is third-person and trigger-rich.
+- [ ] `description` includes both what the skill does and when to use it.
+- [ ] The skill name does not collide with a platform built-in helper unless that is intentional.
+
+## Scope And Boundaries
+
+- [ ] The skill owns one coherent workflow.
+- [ ] `When NOT To Use` or equivalent boundary guidance is present when triggers may overlap.
+- [ ] Project-private rules are in `.trellis/spec/` or a project-local skill, not in a public bundled skill.
+- [ ] The skill distinguishes local project customization from upstream Trellis source changes.
+
+## Entry File
+
+- [ ] `SKILL.md` is concise and under 500 lines.
+- [ ] `SKILL.md` contains the minimum routing and workflow needed to start.
+- [ ] `## Hard Constraints` appears before `## Workflow` when constraints exist.
+- [ ] Hard constraints are imperative one-liners.
+- [ ] The same rule is not repeated in multiple sections.
+
+## References And Assets
+
+- [ ] Long guidance lives in directly linked reference files.
+- [ ] Every referenced file, script, prompt, or example exists.
+- [ ] Reference paths are relative to the skill directory.
+- [ ] Examples demonstrate a complete workflow boundary, not just a fragment.
+
+## Scripts
+
+- [ ] Scripts are necessary for determinism, not decorative.
+- [ ] Scripts expose only necessary parameters.
+- [ ] Scripts do not rely on shell variables or state from a previous tool call.
+- [ ] Scripts return structured JSON when they mutate files or provide machine-readable status.
+- [ ] Syntax checks were run for modified scripts when applicable.
+
+## Trellis Template Integration
+
+- [ ] Bundled skills live under `packages/cli/src/templates/common/bundled-skills/`.
+- [ ] Tests or structured checks confirm platform skill installation and template hash tracking where relevant.
+- [ ] `trellis-meta` references route to this skill where useful without duplicating full authoring rules.
+- [ ] `dist/` was not edited as source.

package/dist/templates/common/bundled-skills/trellis-skill-creator/references/trellis-skill-locations.md

@@ -0,0 +1,52 @@
+# Trellis Skill Locations
+
+Choose the target directory before writing content. Local files are authoritative when they already exist.
+
+## Location Decision Table
+
+| User goal | Default location | Notes |
+| --- | --- | --- |
+| Add a skill for one Trellis project across compatible tools | `.agents/skills/<skill-name>/` | Good default for Codex and tools that read the shared agentskills layer. |
+| Add a skill for one specific platform | Platform skill directory such as `.claude/skills/`, `.cursor/skills/`, `.qoder/skills/`, or `.pi/skills/` | Use when the platform has unique syntax, trigger behavior, or runtime expectations. |
+| Change an existing local Trellis skill | The existing skill directory in the user's project | Preserve local customizations and read the current `SKILL.md` first. |
+| Add a public Trellis bundled skill | `packages/cli/src/templates/common/bundled-skills/<skill-name>/` | Only when working in the Trellis source repository. Update tests that assert bundled skill installation and template tracking. |
+| Add a personal cross-project skill | User's configured global skills directory | Requires explicit user approval because it changes global behavior outside the project. |
+
+## Relationship To `trellis-meta`
+
+Use `trellis-meta` to understand where local Trellis files live and which platform entry point should be changed.
+
+Use `trellis-skill-creator` after the task is clearly about authoring or reviewing the content of a skill:
+
+- frontmatter quality
+- trigger descriptions
+- hard constraints
+- workflow shape
+- references
+- examples
+- deterministic scripts
+- final quality review
+
+Do not copy the full skill-writing guide into `trellis-meta`. `trellis-meta` should route to this skill for detailed authoring guidance.
+
+## Relationship To Cursor `create-skill`
+
+Cursor may provide its own built-in `create-skill` helper. Treat it as a platform-owned helper, not as Trellis source material to edit.
+
+For Trellis work:
+
+- Use `trellis-skill-creator` for Trellis-compatible content and multi-platform boundaries.
+- Keep the skill name `trellis-skill-creator` to avoid colliding with Cursor's built-in skill.
+- If a user explicitly asks for Cursor-only behavior, write to the local `.cursor/skills/` directory and follow the platform's current file format.
+
+## Upstream Bundled Skill Notes
+
+When adding or modifying a bundled skill in the Trellis source repository:
+
+- Do not edit `dist/` directly.
+- Keep the bundled skill public and project-agnostic.
+- Put the skill under `packages/cli/src/templates/common/bundled-skills/`.
+- Include a short `SKILL.md` and lazy-loadable references when the guidance is long.
+- Search for hard-coded bundled skill lists or tests before editing.
+- Update `trellis-meta` only to route users to the new skill where appropriate.
+- Validate template collection, platform installation, and hash tracking with focused tests.

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

@@ -0,0 +1,41 @@
+---
+name: trellis-spec-bootstrap
+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 Bootstrap
+
+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-bootstrap/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
+```