@mindfoldhq/trellis 0.6.0-beta.2 → 0.6.0-beta.21

package/dist/templates/codex/skills/start/SKILL.md

@@ -5,350 +5,60 @@ description: "Initializes an AI development session by reading workflow guides,
 
 # Start Session
 
-Initialize your AI development session and begin working on tasks.
+Initialize a Trellis-managed development session. This platform has no active session-start hook, so manually load the equivalent compact context by following these steps.
 
 ---
 
-## Operation Types
-
-| Marker | Meaning | Executor |
-|--------|---------|----------|
-| `[AI]` | Bash scripts or tool calls executed by AI | You (AI) |
-| `[USER]` | Skills executed by user | User |
-
----
-
-## Initialization `[AI]`
-
-### Step 1: Understand Development Workflow
-
-First, read the workflow guide to understand the development process:
-
-```bash
-cat .trellis/workflow.md
-```
-
-**Follow the instructions in workflow.md** - it contains:
-- Core principles (Read Before Write, Follow Standards, etc.)
-- File system structure
-- Development process
-- Best practices
-
-### Step 2: Get Current Context
-
-```bash
-python3 ./.trellis/scripts/get_context.py
-```
-
-This shows: developer identity, git status, current task (if any), active tasks.
-
-### Step 3: Read Guidelines Index
-
-```bash
-python3 ./.trellis/scripts/get_context.py --mode packages
-```
-
-This shows available packages and their spec layers. Read the relevant spec indexes:
-
-```bash
-cat .trellis/spec/<package>/<layer>/index.md   # Package-specific guidelines
-cat .trellis/spec/guides/index.md              # Thinking guides (always read)
-```
-
-> **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).
-> At this step, just read the indexes to understand what's available.
-> When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist.
-
-### Step 4: Report and Ask
-
-Report what you learned and ask: "What would you like to work on?"
-
----
-
-## Task Classification
-
-When user describes a task, classify it:
-
-| Type | Criteria | Workflow |
-|------|----------|----------|
-| **Question** | User asks about code, architecture, or how something works | Answer directly |
-| **Trivial Fix** | Typo fix, comment update, single-line change, < 5 minutes | Direct Edit |
-| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Task Workflow |
-| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** |
-
-### Decision Rule
-
-> **If in doubt, use Brainstorm + Task Workflow.**
->
-> Task Workflow ensures code-specs are injected to the right context, resulting in higher quality code.
-> The overhead is minimal, but the benefit is significant.
-
-> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
-> consider creating subtasks using `--parent` flag or `add-subtask` command.
-> See the brainstorm skill's Step 8 for details.
-
----
-
-## Question / Trivial Fix
-
-For questions or trivial fixes, work directly:
-
-1. Answer question or make the fix
-2. If code was changed, remind user to run `$finish-work`
-
----
-
-## Simple Task
-
-For simple, well-defined tasks:
-
-1. Quick confirm: "I understand you want to [goal]. Shall I proceed?"
-2. If no, clarify and confirm again
-3. **If yes: execute ALL steps below without stopping. Do NOT ask for additional confirmation between steps.**
-   - Create task directory (Phase 1 Path B, Step 2)
-   - Write PRD (Step 3)
-   - Research codebase (Phase 2, Step 5)
-   - Configure context (Step 6)
-   - Activate task (Step 7)
-   - Implement (Phase 3, Step 8)
-   - Check quality (Step 9)
-   - Complete (Step 10)
-
----
-
-## Complex Task - Brainstorm First
-
-For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation.
-
-See `$brainstorm` for the full process. Summary:
-
-1. **Acknowledge and classify** - State your understanding
-2. **Create task directory** - Track evolving requirements in `prd.md`
-3. **Ask questions one at a time** - Update PRD after each answer
-4. **Propose approaches** - For architectural decisions
-5. **Confirm final requirements** - Get explicit approval
-6. **Proceed to Task Workflow** - With clear requirements in PRD
-
----
-
-## Task Workflow (Development Tasks)
-
-**Why this workflow?**
-- Run a dedicated research pass before coding
-- Configure specs in jsonl context files
-- Implement using injected context
-- Verify with a separate check pass
-- Result: Code that follows project conventions automatically
-
-### Overview: Two Entry Points
-
-```
-From Brainstorm (Complex Task):
-  PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete
-
-From Simple Task:
-  Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete
-```
-
-**Key principle: Research happens AFTER requirements are clear (PRD exists).**
-
----
-
-### Phase 1: Establish Requirements
-
-#### Path A: From Brainstorm (skip to Phase 2)
-
-PRD and task directory already exist from brainstorm. Skip directly to Phase 2.
-
-#### Path B: From Simple Task
-
-**Step 1: Confirm Understanding** `[AI]`
-
-Quick confirm:
-- What is the goal?
-- What type of development? (frontend / backend / fullstack)
-- Any specific requirements or constraints?
-
-If unclear, ask clarifying questions.
-
-**Step 2: Create Task Directory** `[AI]`
+## Step 1: Current state
+Identity, git status, current task, active tasks, journal location.
 
 ```bash
-TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <name>)
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py
 ```
 
-**Step 3: Write PRD** `[AI]`
-
-Create `prd.md` in the task directory with:
-
-```markdown
-# <Task Title>
-
-## Goal
-<What we're trying to achieve>
-
-## Requirements
-- <Requirement 1>
-- <Requirement 2>
-
-## Acceptance Criteria
-- [ ] <Criterion 1>
-- [ ] <Criterion 2>
-
-## Technical Notes
-<Any technical decisions or constraints>
-```
+If this output includes a line beginning `Trellis update available:`, copy the full line verbatim when summarizing session context. Do not shorten operational command hints.
 
----
-
-### Phase 2: Prepare for Implementation (shared)
-
-> Both paths converge here. PRD and task directory must exist before proceeding.
-
-**Step 4: Code-Spec Depth Check** `[AI]`
-
-If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined.
-
-Trigger this requirement when the change includes any of:
-- New or changed command/API signatures
-- Database schema or migration changes
-- Infra integrations (storage, queue, cache, secrets, env contracts)
-- Cross-layer payload transformations
-
-Must-have before proceeding:
-- [ ] Target code-spec files to update are identified
-- [ ] Concrete contract is defined (signature, fields, env keys)
-- [ ] Validation and error matrix is defined
-- [ ] At least one Good/Base/Bad case is defined
-
-**Step 5: Research the Codebase** `[AI]`
-
-Based on the confirmed PRD, run a focused research pass and produce:
-
-1. Relevant spec files in `.trellis/spec/`
-2. Existing code patterns to follow (2-3 examples)
-3. Files that will likely need modification
-
-Use this output format:
-
-```markdown
-## Relevant Specs
-- <path>: <why it's relevant>
-
-## Code Patterns Found
-- <pattern>: <example file path>
-
-## Files to Modify
-- <path>: <what change>
-```
-
-**Step 6: Configure Context** `[AI]`
-
-`implement.jsonl` and `check.jsonl` were seeded on `task.py create` with a single self-describing `_example` line. Curate real entries now (see workflow.md Phase 1.3 for the full rule):
-
-- Put **spec files** (`.trellis/spec/<package>/<layer>/*.md`) and **research files** (`{TASK_DIR}/research/*.md`) only.
-- Do NOT put code files (`src/**`, `packages/**`) — those are read during implementation, not pre-registered here.
-- Split: `implement.jsonl` = specs the implement sub-agent needs; `check.jsonl` = specs the check sub-agent needs.
-
-Discover available specs:
+## Step 2: Workflow overview
+Compact Phase Index, request triage rules, planning artifact contract, and the step-detail command.
 
 ```bash
-python3 ./.trellis/scripts/get_context.py --mode packages
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase
 ```
 
-Append entries (either edit the jsonl file directly, or):
+Full guide in `.trellis/workflow.md` (read on demand).
 
-```bash
-python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
-python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
-```
-
-**Step 7: Activate Task** `[AI]`
+## Step 3: Guideline indexes
+Discover packages + spec layers, then read each relevant index file.
 
 ```bash
-python3 ./.trellis/scripts/task.py start "$TASK_DIR"
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode packages
+cat .trellis/spec/guides/index.md
+cat .trellis/spec/<package>/<layer>/index.md   # for each relevant layer
 ```
 
-This sets the active task through Trellis' session resolver so hooks can inject context for this AI session. If the command fails because no session identity is available, rerun it from an IDE/session that exposes session identity or set `TRELLIS_CONTEXT_ID`.
-
----
-
-### Phase 3: Execute (shared)
-
-**Step 8: Implement** `[AI]`
-
-Implement the task described in `prd.md`.
-
-- Follow all specs injected into implement context
-- Keep changes scoped to requirements
-- Run lint and typecheck before finishing
-
-**Step 9: Check Quality** `[AI]`
-
-Run a quality pass against check context:
+Index files list the specific guideline docs to read when you actually start coding.
 
-- Review all code changes against the specs
-- Fix issues directly
-- Ensure lint and typecheck pass
+## Step 4: Decide next action
+From Step 1 you know the current task and status. Check the task directory:
 
-**Step 10: Complete** `[AI]`
-
-1. Verify lint and typecheck pass
-2. Report what was implemented
-3. Remind user to:
-   - Test the changes
-   - Commit when ready
-   - Run `$record-session` to record this session
-
----
-
-## Continuing Existing Task
-
-If `get_context.py` shows a current task:
-
-1. Read the task's `prd.md` to understand the goal
-2. Check `task.json` for current status and phase
-3. Ask user: "Continue working on <task-name>?"
-
-If yes, resume from the appropriate step (usually Step 7 or 8).
+- **Active task status `planning` + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
+- **Active task status `planning` + `prd.md` exists** → stay in Phase 1. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. Load the relevant Phase 1 step detail before `task.py start`.
+- **Active task status `in_progress`** → Phase 2 step 2.1. Load the step detail:
+  ```bash
+  {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform {{CLI_FLAG}}
+  ```
+- **No active task** → classify first. For simple conversation / small task, ask only whether this turn should create a Trellis task. For complex work, ask whether you may create a Trellis task and enter planning. If the user says no, skip Trellis for this session.
 
 ---
 
-## Skills Reference
-
-### User Skills `[USER]`
-
-| Skill | When to Use |
-|---------|-------------|
-| `$start` | Begin a session (this skill) |
-| `$finish-work` | Before committing changes |
-| `$record-session` | After completing a task |
-
-### AI Scripts `[AI]`
-
-| Script | Purpose |
-|--------|---------|
-| `python3 ./.trellis/scripts/get_context.py` | Get session context |
-| `python3 ./.trellis/scripts/task.py create` | Create task directory (seeds jsonl on sub-agent platforms) |
-| `python3 ./.trellis/scripts/task.py add-context` | Append spec/research entry to jsonl |
-| `python3 ./.trellis/scripts/task.py start` | Set current task |
-| `python3 ./.trellis/scripts/task.py finish` | Clear current task |
-| `python3 ./.trellis/scripts/task.py archive` | Archive completed task |
-
-### Workflow Phases `[AI]`
-
-| Phase | Purpose | Context Source |
-|-------|---------|----------------|
-| research | Analyze codebase | direct repo inspection |
-| implement | Write code | `implement.jsonl` |
-| check | Review & fix | `check.jsonl` |
-| debug | Fix specific issues | `debug.jsonl` |
-
----
+## Skill routing (quick reference)
 
-## Key Principle
+| User intent | Skill |
+|---|---|
+| New feature / unclear requirements | `trellis-brainstorm` |
+| About to write code | `trellis-before-dev` |
+| Done coding / quality check | `trellis-check` |
+| Stuck / fixed same bug multiple times | `trellis-break-loop` |
+| Learned something worth capturing | `trellis-update-spec` |
 
-> **Code-spec context is injected, not remembered.**
->
-> The Task Workflow ensures agents receive relevant code-spec context automatically.
-> This is more reliable than hoping the AI "remembers" conventions.
+Full rules + anti-rationalization table in `.trellis/workflow.md`.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-context-loading.md

@@ -18,6 +18,8 @@ Context loading determines when AI reads workflow, task, spec, research, workspa
 | --- | --- |
 | `.trellis/workflow.md` | Workflow and next-action hints. |
 | `.trellis/tasks/<task>/prd.md` | Current task requirements. |
+| `.trellis/tasks/<task>/design.md` | Complex task technical design. |
+| `.trellis/tasks/<task>/implement.md` | Complex task execution plan. |
 | `.trellis/tasks/<task>/implement.jsonl` | Spec/research to read before implementation. |
 | `.trellis/tasks/<task>/check.jsonl` | Spec/research to read during checking. |
 | `.trellis/spec/` | Project specs. |
@@ -64,10 +66,11 @@ First determine which mode the platform uses:
 In both modes, make sure the agent ultimately reads:
 
 1. active task
-2. `prd.md`
-3. `info.md` if present
-4. the corresponding JSONL
-5. spec/research referenced by the JSONL
+2. the corresponding JSONL
+3. spec/research referenced by the JSONL
+4. `prd.md`
+5. `design.md` if present
+6. `implement.md` if present
 
 ## Troubleshooting Order
 

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-spec-structure.md

@@ -6,7 +6,7 @@ When the user wants to change the engineering conventions AI follows, add new sp
 
 1. `.trellis/config.yaml`
 2. `.trellis/spec/`
-3. `.trellis/workflow.md` Phase 1.3 and Phase 3.3
+3. `.trellis/workflow.md` planning artifact guidance and Phase 3.3
 4. Current task `implement.jsonl` / `check.jsonl`
 
 ## Common Needs

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-workflow.md

@@ -50,8 +50,9 @@ If the user wants only one platform to avoid sub-agents, first confirm whether t
 | `status` | Artifact state | Resume at |
 | --- | --- | --- |
 | `planning` | `prd.md` missing | Phase 1.1 (load `trellis-brainstorm`) |
-| `planning` | `prd.md` exists, `implement.jsonl` only has the seed `_example` row | Phase 1.3 (curate JSONL context) |
-| `planning` | `prd.md` exists, `implement.jsonl` curated | Phase 1.4 (run `task.py start`) |
+| `planning` | lightweight task with `prd.md` complete | ask for start review, then run `task.py start` |
+| `planning` | complex task missing `design.md` or `implement.md` | complete missing planning artifacts |
+| `planning` | complex task has `prd.md`, `design.md`, and `implement.md` | ask for start review, then run `task.py start` |
 | `in_progress` | no implementation in conversation history | Phase 2.1 (`trellis-implement`) |
 | `in_progress` | implementation done, no `trellis-check` run | Phase 2.2 (`trellis-check`) |
 | `in_progress` | check passed | Phase 3.1 (verify quality + spec update) |

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/context-injection.md

@@ -9,7 +9,7 @@ Trellis context injection aims to make AI read the right files at the right time
 | session context | `.trellis/scripts/get_context.py` | Current developer, git status, active task, active tasks, journal, packages. |
 | workflow context | `.trellis/workflow.md` | Current Trellis flow and next action. |
 | spec context | `.trellis/spec/` + task JSONL | Specs that must be followed during implementation/checking. |
-| task context | `.trellis/tasks/<task>/prd.md`, `info.md`, `research/` | Current task requirements, design, and research. |
+| task context | `.trellis/tasks/<task>/prd.md`, `design.md`, `implement.md`, `research/` | Current task requirements, design, execution plan, and research. |
 | platform context | Platform hooks/settings/agents | Lets different AI tools read the files above through their own mechanisms. |
 
 ## session-start
@@ -34,10 +34,10 @@ If the user wants to change "what the AI should do next in a given state," edit
 
 Implement and check agents need task context. Trellis has two loading modes:
 
-1. **hook push**: a platform hook injects `prd.md` and the files referenced by `implement.jsonl` / `check.jsonl` before the agent starts.
-2. **agent pull**: the agent definition instructs the agent to read the active task, PRD, and JSONL context after startup.
+1. **hook push**: a platform hook injects jsonl-referenced files plus `prd.md`, `design.md` if present, and `implement.md` if present before the agent starts.
+2. **agent pull**: the agent definition instructs the agent to read the active task, jsonl context, and task artifacts after startup.
 
-In both modes, JSONL files in the task directory are the key interface.
+In both modes, JSONL files in the task directory are the manifest for spec/research context. Task artifacts are read separately in this order: `prd.md` -> `design.md if present` -> `implement.md if present`.
 
 ## JSONL Reading Rules
 
@@ -65,4 +65,4 @@ If shell commands cannot see the same context key, `task.py current --source` ma
 | Change JSONL validation/display | `.trellis/scripts/common/task_context.py`. |
 | Change active task resolution | `.trellis/scripts/common/active_task.py`. |
 
-When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct PRD/spec/research.
+When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct task artifacts/spec/research.

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/spec-system.md

@@ -65,7 +65,7 @@ This command lists packages and spec layers for the current project. Use this ou
 
 ## How Specs Enter Tasks
 
-Before a task enters implementation, Phase 1.3 should write relevant specs into `implement.jsonl` / `check.jsonl`:
+Before a task enters implementation, planning may write relevant specs into `implement.jsonl` / `check.jsonl` when the task needs spec or research context beyond the task artifacts:
 
 ```jsonl
 {"file": ".trellis/spec/cli/backend/index.md", "reason": "CLI backend conventions"}

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/task-system.md

@@ -9,7 +9,8 @@ The Trellis task system is stored entirely under `.trellis/tasks/` in the user p
 ├── 04-28-example-task/
 │   ├── task.json
 │   ├── prd.md
-│   ├── info.md
+│   ├── design.md
+│   ├── implement.md
 │   ├── implement.jsonl
 │   ├── check.jsonl
 │   └── research/
@@ -20,8 +21,9 @@ The Trellis task system is stored entirely under `.trellis/tasks/` in the user p
 | File | Purpose |
 | --- | --- |
 | `task.json` | Task metadata: status, assignee, priority, branch, parent/child tasks, and similar fields. |
-| `prd.md` | Requirements document; the most important business context during implementation. |
-| `info.md` | Optional technical design. |
+| `prd.md` | Requirements, constraints, and acceptance criteria. Lightweight tasks may be PRD-only. |
+| `design.md` | Technical design for complex tasks: boundaries, contracts, data flow, compatibility, tradeoffs. |
+| `implement.md` | Execution plan for complex tasks: ordered checklist, validation commands, review gates, rollback points. |
 | `implement.jsonl` | List of spec/research files the implement agent must read first. |
 | `check.jsonl` | List of spec/research files the check agent must read first. |
 | `research/` | Research artifacts. Complex findings should not live only in chat. |
@@ -42,7 +44,34 @@ The Trellis task system is stored entirely under `.trellis/tasks/` in the user p
 | `commit` / `pr_url` | Commit and PR information after completion. |
 | `meta` | Extension fields. |
 
-The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, `prd.md`, whether JSONL context is configured, and the phase descriptions in `workflow.md`.
+## Parent / Child Task Trees
+
+Parent/child task relationships are for work structure. A parent task groups related deliverables under one source requirement set; it is not a dependency scheduler and does not replace the child task's own planning artifacts.
+
+Use a parent task when a request has multiple independently verifiable deliverables. The parent owns:
+
+- Source requirements and user-facing scope.
+- The map of child tasks and their responsibility boundaries.
+- Cross-child acceptance criteria and final integration review.
+
+Use child tasks for deliverables that can move through planning, implementation, check, and archive independently. If one child depends on another, write that dependency in the child `prd.md` / `implement.md`; do not rely on tree position to imply ordering.
+
+Create new children with:
+
+```bash
+python3 ./.trellis/scripts/task.py create "<child title>" --slug <child-slug> --parent <parent-dir>
+```
+
+Link or unlink existing tasks with:
+
+```bash
+python3 ./.trellis/scripts/task.py add-subtask <parent-dir> <child-dir>
+python3 ./.trellis/scripts/task.py remove-subtask <parent-dir> <child-dir>
+```
+
+`children` on the parent is a historical list. When a child is archived, Trellis keeps that child name in the parent so progress like `[2/3 done]` remains meaningful after completed children move to `archive/`.
+
+The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, artifact presence (`prd.md`, optional `design.md` / `implement.md`), whether JSONL context is configured for sub-agent mode, and the phase descriptions in `workflow.md`.
 
 ## Active Task
 
@@ -58,7 +87,7 @@ If the platform or shell environment has no stable session identity, `task.py st
 
 ## JSONL Context
 
-`implement.jsonl` and `check.jsonl` are context manifests for sub-agents to read first.
+`implement.jsonl` and `check.jsonl` are context manifests for sub-agents to read first. They do not replace `implement.md`; `implement.md` is the human-readable execution plan.
 
 Format:
 
@@ -95,7 +124,7 @@ When modifying the task system, the AI should prefer script commands to maintain
 | Change the default task template | `.trellis/scripts/common/task_store.py` and task creation instructions. |
 | Change status semantics | `.trellis/workflow.md`, workflow-state hook logic, and task usage conventions. |
 | Add task lifecycle actions | `hooks.after_*` in `.trellis/config.yaml`. |
-| Change context rules | Phase 1.3 in `.trellis/workflow.md` and related platform agent/hook instructions. |
+| Change context rules | Planning artifact guidance in `.trellis/workflow.md` and related platform agent/hook instructions. |
 | Change archive policy | `.trellis/scripts/common/task_store.py` / `task_utils.py`. |
 
 These are local files in the user project. Do not default to editing Trellis CLI source code unless the user wants to contribute upstream.

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

@@ -13,7 +13,7 @@ File locations and formats differ by platform, but responsibility boundaries sho
 | 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-implement` | Implement against `prd.md`, optional `design.md` / `implement.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.
@@ -50,10 +50,11 @@ Common on platforms that support agent hooks.
 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
+- current task `prd.md`
+- `design.md` if present
+- `implement.md` if present
 
 This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts.
 
@@ -70,7 +71,7 @@ This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts.
 ## 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.
+2. **Specify the read order**. Agents must know to start from the active task, read jsonl/spec context, then read `prd.md`, `design.md` if present, and `implement.md` if present.
 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.
 

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.