Why Trellis-Gun-plus?

| Capability | What it changes | | --- | --- | | Auto-injected specs | Write conventions once in .trellis/spec/, then let Trellis inject the relevant context into each session instead of repeating yourself. | | Task-centered workflow | Keep PRDs, implementation context, review context, and task status in .trellis/tasks/ so AI work stays structured. | | Long task mode | Decompose complex work into .trellis/tasks/<task>/long-task.csv, then resume from disk if the session is interrupted. | | Project memory | Journals in .trellis/workspace/ preserve what happened last time, so each new session starts with real context. | | Team-shared standards | Specs live in the repo, so one person's hard-won workflow or rule can benefit the whole team. | | Multi-platform setup | Bring the same Trellis structure to 14 AI coding platforms instead of rebuilding your workflow per tool. |

Prerequisites:

• Node.js >= 18
• Python >= 3.9

Quick Start

# 1. Install Trellis-Gun-plus
npm install -g trellis-gun-plus@latest

# 2. Initialize in your repo
trellis init -u your-name

# 3. Or initialize with the platforms you actually use
trellis init --cursor --opencode --codex -u your-name

See the Quick Start and Supported Platforms guides for setup details.

How to Use

The workflow is simple:

1. Describe what you want in natural language.
2. Brainstorm with the AI one question at a time until the PRD is clear, then implementation begins.
3. Use long task mode for big work — when the request is a broad refactor, multi-step feature, or recoverable long-running task, load trellis-long-task; Trellis writes a long-task.csv ledger inside the task directory and continues through trellis-task-execute.
4. Let it run — the AI calls Trellis Implement and auto-checks the result against specs, lint, type-check, and tests.
5. Type /trellis:finish-work when the work is done or the session context fills up. Trellis-Gun-plus archives the task and updates journals.

How to Use Long Task Mode

When a request may span multiple files, validation steps, or sessions, say that you want long task mode in the request:

Use long task mode to refactor the editor: split state management first, then update the UI, then add tests and docs.

Trellis-Gun-plus then follows this flow:

1. Create or reuse the task directory — trellis-long-task creates .trellis/tasks/<task>/, or completes prd.md in an existing planning task.
2. Write the task boundary — prd.md records the original request, goals, non-goals, constraints, acceptance criteria, and validation plan.
3. Create the execution ledger — long-task.csv is split into 3-12 independently verifiable rows, plus a final REVIEW-01 row for whole-task acceptance.
4. Advance row by row — trellis-task-execute resumes any in_progress row first, then chooses the next row by priority and phase.
5. Persist state after each meaningful action — implementation, review, validation, file references, and evidence are written back to the CSV.
6. Recover from interruption — after context loss, say "continue this long task"; trellis-task-recovery scans unfinished ledgers and resumes from the next incomplete row.

The important long-task.csv fields are:

| Field | Purpose | | --- | --- | | id | Stable row ID, such as API-01, UI-02, or REVIEW-01 | | priority / phase | Controls execution and recovery order | | area / title / description | Defines where the row works and what it changes | | acceptance_criteria | Observable completion criteria, not a vague "finish cleanup" note | | validation | Concrete checks, commands, builds, tests, or manual verification steps | | required_skills | Skills needed for the row; code-editing rows usually include trellis-before-dev | | review_requirements | What trellis-check must verify before closure | | dev_state | not_started, in_progress, or done | | review_state | not_started, in_progress, or done | | git_state | not_committed or committed; only mark committed after a real commit | | refs | Relevant source files, PRD lines, tests, or docs | | notes | Validation evidence, limited-validation notes, risk notes, and state repairs |

Use trellis-brainstorm first when the requirements are still unclear. Do not mark a row done without validation evidence. If your project does not allow automatic commits, rows can keep git_state=not_committed while the implementation and review evidence remain recorded in the ledger.

How It Works

Trellis-Gun-plus runs a 4-phase loop with auto-invoked skills and sub-agents:

1. Plan — trellis-brainstorm walks through requirements one question at a time and writes prd.md. Research-heavy items go to a trellis-research sub-agent. The result is curated specs + research files referenced from implement.jsonl / check.jsonl.
2. Implement — a trellis-implement sub-agent writes code from the PRD with the curated context auto-injected, no git commit.
3. Verify — a trellis-check sub-agent reviews the diff against specs and runs lint, type-check, and tests, self-fixing where it can.
4. Finish — a final check runs, then trellis-update-spec promotes new learnings back into .trellis/spec/ so the next session starts smarter.

For larger work, trellis-long-task adds a persistent execution ledger at .trellis/tasks/<task>/long-task.csv. trellis-task-execute advances each row through implementation, review, validation, and commit state, while trellis-task-recovery can scan unfinished ledgers and resume from the next incomplete row.

Resources

| Need | Link | | ------------------------------- | ------------------------------------------------------------------------------ | | Install Trellis in a repo | Quick Start | | Understand platform differences | Supported Platforms | | See the workflow in practice | Real-World Scenarios | | Start from spec templates | Spec Templates | | Track releases | Changelog |

FAQ

Those files are useful entry points, but they tend to become monolithic. Trellis-Gun-plus adds scoped specs, task PRDs, workflow gates, workspace memory, and platform-aware generated files around them.

No. Trellis-Gun-plus is a project layer that works across multiple coding agents and IDEs.

Both. Solo developers use it for memory and repeatable workflow. Teams get the larger benefit: shared standards, task boundaries, reviewable context, and platform portability.

No. Many teams start by letting AI draft specs from existing code and then tighten the important parts by hand. Trellis-Gun-plus works best when you keep the high-signal rules explicit and versioned.

Yes. Personal workspace journals stay separate per developer, while shared specs and tasks stay in the repo where they can be reviewed and improved like any other project artifact.

Star History

Community & Resources

• Official Docs
• GitHub Issues
• Discord
• Tech Blog