Skill and agent instructions should enforce mandatory artifact reads and explicit out-artifact lifecycle

[nullhack]

Problem

The current skill/agent instructions have three issues that cause rework during state-machine-driven development:

1. Input artifacts are treated as optional, on-demand reads

Skills instruct agents to "discover and read on demand as needed," which leads to agents skipping critical input artifacts. When in artifacts are listed in a flow state, they define mandatory context — the agent should read all of them before starting work, not selectively pick what seems relevant. Skipping inputs causes agents to build on assumptions about documents they haven't actually read.

Fix: Change in artifact handling from "discover and read on demand" to "read all before starting work." Wildcard patterns (*.md) should still list the directory first to discover files, but then all discovered files must be read.

2. No explicit out-artifact lifecycle protocol

When a flow state declares out artifacts with section sub-lists, agents have no clear protocol for handling file creation vs. editing. This leads to:

• Overwriting existing files instead of editing specific sections
• Not knowing how to create a file from a template when it doesn't exist yet
• No guidance on template path resolution conventions

Fix: Add a clear out-artifact protocol:

1. Check if the file exists on disk
2. If it exists → read it, edit only the declared sections, preserve the rest
3. If it doesn't exist → resolve the template path (destination → .templates/ + destination + .template), copy template to destination, then edit declared sections
4. If no template exists → raise an error for the stakeholder

3. No cumulative editing guidance for loop-back states

When a flow loops back to a previously executed state (e.g., needs_reinterview → interview → back to event storming), agents recreate the out artifact from scratch instead of editing the existing one. Artifacts like event storming maps, glossaries, and domain models accumulate knowledge across iterations — they must be edited, not replaced.

Fix: Add a "cumulative editing" rule: when a flow re-enters a state that was previously executed, the out artifact is edited, not recreated. The agent reads the existing file, incorporates new information, and adjusts existing content. Skills that are likely targets of loop-back (event storming, domain modeling, glossary definition) should have explicit steps for this.

Affected files (framework-level)

• AGENTS.md — session protocol step 3, "Within a State" section (artifact contract, out-artifact protocol)
• .opencode/knowledge/skill-design/principles.md — Input Handling section, skill body template
• .opencode/skills/*/SKILL.md — all skill headers referencing "on demand" reading
• .opencode/skills/facilitate-event-storming/SKILL.md — add cumulative editing steps (example for other loop-back-prone skills)