trellis-update-spec

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Valuable lessons from debugging, feature implementation, and design discussions are often lost between sessions, forcing developers and AI agents to rediscover the same contracts, conventions, and pitfalls repeatedly. ## Core Features & Use Cases - Executable Contract Capture: Records concrete signatures, request/response fields, environment keys, and validation/error matrices into .trellis/spec/ documents rather than vague principles. - Spec vs Guide Classification: Distinguishes code-specs (how to implement) from guides (what to think about) so knowledge lands in the correct location. - Structured Update Templates: Provides ready-made templates for design decisions, conventions, patterns, forbidden patterns, common mistakes, and gotchas. - Use Case: After fixing a subtle cross-layer API bug, use this Skill to document the corrected request contract, error matrix, and a wrong-vs-correct example so future sessions never repeat the mistake. ## Quick Start Ask the AI to update the relevant .trellis/spec/ document with the contract and lessons learned from the task you just completed.

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 API contracts after implementing a feature?

Update the relevant .trellis/spec/ layer file with the mandatory seven sections: scope, signatures, contracts, validation and error matrix, good/base/bad cases, required tests, and a wrong-versus-correct pair. This applies whenever commands, APIs, or schemas change.

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

Code-specs live in per-layer directories and describe how to implement safely with signatures, contracts, and test points. Guides live in guides/ and are short thinking checklists pointing to specs. Concrete conventions go in specs; abstract reminders go in guides.

When should I update a spec document?

Update after implementing a feature, fixing a bug, making a design decision, discovering a pattern, hitting a gotcha, or establishing a convention. Spec updates are mandatory for infra or cross-layer contract changes.

What sections are required for infrastructure or cross-layer changes?

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

Where should a thinking checklist item be documented?

Thinking checklists belong in .trellis/spec/guides/ as short items that point to detailed specs, not in layer spec files. Guides answer what to consider before writing code, while specs answer how to write it.