docs(openspec): set up OpenSpec baseline (config + principles + glossary)

[drakulavich]

Summary

Sets up OpenSpec for Iago, mirroring the layout used by kesha-voice-kit, ottoman, and bowser: a config.yaml carrying project context + spec-writing rules, plus a specs/ README and glossary. Future work can then be proposed as OpenSpec change deltas against a consistent baseline.

The spec-writing rules are the Pareto core of Joel Spolsky's painless-functional-spec structure (Non-Goals first-class, outcomes not implementation in requirement text, Open Issues first-class) crossed with Nikita Sobolev's user-story lenses (named personas, glossary terms verbatim, every requirement verifiable with a happy and an error scenario), plus file:line traceability.

What's added

File	Purpose
openspec/config.yaml	schema + context (Iago's conventions — skill-first, host-agent LLM draws the diagram, bun + gh only, no Action, dependency-free skill folder, Mermaid reserved-keyword safety, gh -f raw-field, version alignment) + rules (1 proposal rule, 6 spec rules).
openspec/specs/README.md	Disclaimer, spec shape, three personas (Pasha the review author / Devin the toolchain integrator / Mira the skill maintainer), planned capability table.
openspec/specs/GLOSSARY.md	Canonical terms (Skill, Host agent, Diagram type, /review comment, post.ts, …), each traced to the repo.

The seven rules (config.yaml rules)

• Non-goals section in every proposal
• Glossary terms verbatim
• Every requirement: happy-path and error/edge scenario
• Outcomes, not implementation, in requirement text
• Named personas (Pasha/Devin/Mira), never a generic "user"
• Uncertainty / spec-vs-code drift under "Open Issues" — never invent a resolution
• Trace each requirement to code with file:line refs in a Technical Note

Notes

• No spec.md files yet — specs/ fills in as capabilities are extracted (the README table links them in then).
• Iago's runtime is bun + gh (npx also works), so no bun-only rule is imposed.
• Files staged explicitly per CLAUDE.md (never git add -A).
• config.yaml mirrors the schema validated under openspec validate --specs --strict elsewhere; the OpenSpec CLI tooling can be added separately if you want the in-editor workflow.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR establishes the OpenSpec baseline for Iago — a config.yaml with project context and seven spec-writing rules, a specs/README.md defining the corpus structure and three named personas, and a specs/GLOSSARY.md with 18 canonical terms traced to source files.

• openspec/config.yaml encodes the critical project constraints (bun + gh only, no Action, dependency-free skill folder, -f raw-field, version alignment) alongside proposal and spec rules derived from Spolsky/Sobolev conventions.
• openspec/specs/GLOSSARY.md provides 18 canonical terms with file:line traceability; the post.ts:50-51 citation for "Append (squawk)" was verified accurate against the current source.
• openspec/specs/README.md describes spec shape, personas (Pasha / Devin / Mira), and a capability table whose rows are intentionally unlinked until individual spec.md files land.

Confidence Score: 5/5

Documentation-only change with no runtime code; all file and line references were verified against the current codebase.

All three new files are pure documentation. Every file:line citation in the glossary (post.ts:50-51, sanitize.ts, diagram-selection.md, mermaid-templates.md) points to files that exist and contain exactly what is described. Terminology is internally consistent across config.yaml, GLOSSARY.md, and README.md. The previously flagged 'on top of' wording has been corrected to 'appending … to the end of'. No executable code is introduced.

No files require special attention.

Important Files Changed

Filename	Overview
openspec/config.yaml	Adds OpenSpec configuration with project context and seven spec-writing rules; all referenced paths and constraints are accurate against the codebase.
openspec/specs/GLOSSARY.md	Defines 18 canonical terms with file:line traceability; all referenced files exist and the post.ts:50-51 citation for the Append behavior is verified accurate.
openspec/specs/README.md	Establishes spec corpus structure, three named personas, and a capability table; clearly marks all spec entries as unlinked until individual spec.md files land.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[OpenSpec baseline] --> B[openspec/config.yaml]
    A --> C[openspec/specs/README.md]
    A --> D[openspec/specs/GLOSSARY.md]

    B --> B1[schema: spec-driven]
    B --> B2[context: project constraints\nbun+gh, no Action, -f flag,\ndependency-free scripts]
    B --> B3[rules: proposal + 6 spec rules\nNon-goals / personas / traceability\nhappy+error scenarios / Open Issues]

    C --> C1[Spec shape\nPurpose / Non-Goals / Requirements\nTechnical Notes / Open Issues]
    C --> C2[Personas\nPasha / Devin / Mira]
    C --> C3[Capabilities table\ndiagram-append / diagram-selection\nmermaid-authoring / installer-cli / distribution]

    D --> D1[18 canonical terms\nSkill / Host agent / Diagram type\npost.ts / sanitize.ts / Runtime]
    D1 -- file:line refs --> E[iago/scripts/post.ts:50-51\niago/scripts/sanitize.ts\niago/references/*.md]

    B3 -. governs future .-> F[specs/name/spec.md\neach capability]
    C3 -. links once written .-> F

Loading

_{Reviews (2): Last reviewed commit: "docs(openspec): clarify Append definitio..." | Re-trigger Greptile}