trellis-update-spec

Update Code-Spec - Capture Executable Contracts

When you learn something valuable (from debugging, implementing, or discussion), use this to update the relevant code-spec documents.

Timing: After completing a task, fixing a bug, or discovering a new pattern

---

Code-Spec First Rule (CRITICAL)

In this project, "spec" for implementation work means code-spec:

• Executable contracts (not principle-only text)
• Concrete signatures, payload fields, env keys, and boundary behavior
• Testable validation/error behavior

If the change touches infra or cross-layer contracts, code-spec depth is mandatory.

Mandatory Triggers

Apply code-spec depth when the change includes any of:

• New/changed command or API signature
• Cross-layer request/response contract change
• Database schema/migration change
• Infra integration (storage, queue, cache, secrets, env wiring)

Mandatory Output (7 Sections)

For triggered tasks, include all sections below:

1. Scope / Trigger
2. Signatures (command/API/DB)
3. Contracts (request/response/env)
4. Validation & Error Matrix
5. Good/Base/Bad Cases
6. Tests Required (with assertion points)
7. Wrong vs Correct (at least one pair)

---

When to Update Code-Specs

| Trigger | Example | Target Spec | |---------|---------|-------------| | Implemented a feature | Added a new integration or module | Relevant spec file | | Made a design decision | Chose extensibility pattern over simplicity | Relevant spec + "Design Decisions" section | | Fixed a bug | Found a subtle issue with error handling | Relevant spec (e.g., error-handling docs) | | Discovered a pattern | Found a better way to structure code | Relevant spec file | | Hit a gotcha | Learned that X must be done before Y | Relevant spec + "Common Mistakes" section | | Established a convention | Team agreed on naming pattern | Quality guidelines | | New thinking trigger | "Don't forget to check X before doing Y" | guides/*.md (as a checklist item) |

Key Insight: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.

---

Spec Structure Overview

…

Install

Ships with Trellis. After trellis init, this skill is available under .agents/skills/trellis-update-spec/ (and platform skill dirs).

npm install -g @mindfoldhq/trellis@latest
trellis init -u your-name

Source: mindfold-ai/Trellis · .agents/skills/trellis-update-spec