trellis-update-spec

Captures executable contracts and coding conventions into .trellis/spec/ documentation files.

Updated Jun 8, 2026
One-click install
npx skills add https://github.com/dev2019zheng/codex-beacon --skill trellis-update-spec-dev2019zheng
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: trellis-update-spec
Source: https://github.com/dev2019zheng/codex-beacon/tree/main/.cursor/skills/trellis-update-spec
Command: npx skills add https://github.com/dev2019zheng/codex-beacon --skill trellis-update-spec-dev2019zheng

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Valuable lessons from debugging sessions, feature implementations, and design discussions are often lost between sessions, forcing developers and AI assistants to rediscover the same patterns and mistakes. This Skill preserves that knowledge as executable code-specs with concrete signatures, contracts, and test requirements. ## Core Features & Use Cases - Executable Contract Capture: Records command/API signatures, request/response fields, environment keys, and validation error matrices rather than abstract principles. - Spec vs Guide Classification: Routes content to layer-specific spec files for implementation rules or guides/ checklists for thinking prompts. - Structured Update Templates: Provides ready-made templates for design decisions, conventions, patterns, anti-patterns, common mistakes, and gotchas. - Use Case: After fixing a subtle cross-layer API bug, use this Skill to document the correct request contract, error matrix, and a wrong-vs-correct example in the relevant .trellis/spec/ file so future sessions avoid the same mistake. ## Quick Start Update the relevant code-spec in .trellis/spec/ with the validation rules and error handling pattern we just discovered while fixing the API bug.

Frequently Asked Questions about trellis-update-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document design decisions from a coding session?

Use the design decision template to record the context, options considered, the chosen approach with reasoning, and a code example. Add it to the relevant spec file's Design Decisions section so future sessions understand why the approach was selected.

What is the difference between a code-spec and a guide?

Code-specs live in layer directories and contain executable contracts like signatures, payload fields, and error matrices that tell you how to implement. Guides live in guides/ and are short thinking checklists about what to consider before writing code.

When should I update a code-spec after implementing a feature?

Update whenever you make a design decision, fix a bug, discover a pattern, hit a gotcha, or establish a convention. Infra or cross-layer contract changes like new API signatures or schema migrations always require the full seven-section code-spec depth.

What sections are required for infrastructure or API contract changes?

Seven sections are mandatory: Scope/Trigger, Signatures, Contracts, Validation and Error Matrix, Good/Base/Bad Cases, Tests Required with assertion points, and at least one Wrong vs Correct pair.

Where should coding conventions be documented in a project?

Conventions belong in the relevant layer-specific spec file under .trellis/spec/, not in guides. Include what the convention is, why the project follows it, a code example, and links to related specs.