Skip to content

CONTRACT.md

Latest commit

 

History

History
103 lines (85 loc) · 7.67 KB

CONTRACT.md

File metadata and controls

103 lines (85 loc) · 7.67 KB

trio-dev contract

Single source of truth for what each step of the trio-dev workflow reads, writes, and hands off to next. The smoke test in scripts/smoke-test.sh verifies that commands/, skills/, CONTRACT.md, and the installer scripts all agree. When you change a file name, add a step, or change dispatch mechanics, update this file first, then run the smoke test.

Slash commands (must all exist in commands/)

Command File Next command the prompt may reference
/trio-build commands/trio-build.md /trio-continue, /trio-finalize
/trio-continue commands/trio-continue.md /trio-finalize
/trio-finalize commands/trio-finalize.md (terminal — ship or fix)
/trio-design commands/trio-design.md (terminal — user replies "done" in chat)
/trio-plan commands/trio-plan.md (terminal — user replies "done" in chat)
/trio-code commands/trio-code.md /trio-finalize
/trio-test commands/trio-test.md (terminal — diagnostic only)

No other slash command may be mentioned in any commands/*.md or skills/*/SKILL.md. The smoke test fails if a command references a file that does not exist (it filters out explicit disowning phrasing like "there is no /trio-foo").

Dispatch mechanism — wrapper scripts (v0.2.0+)

All cross-model calls go through ~/.claude/bin/*.sh wrappers invoked by Claude via the Bash tool. Manager View dispatch is not part of the happy path; it is documented as a manual fallback only.

Wrapper Input Output file(s)
ask-gemini.sh SYS USR OUT system-prompt file, user-prompt file OUT (the model's final response)
ask-codex.sh SYS USR OUT same OUT
trio-design.sh "<request>" request arg, .trio/project-context.md .trio/design.md
trio-plan.sh "<request>" request arg, .trio/design.md if present .trio/plan.md, .trio/tests.md
trio-review.sh gemini .trio/brief,plan,tests,design,SUMMARY.md, git log .trio/review-gemini.md
trio-review.sh codex same .trio/review-gpt.md (note: gpt, not codex)

Preflight rule: every command that dispatches a wrapper first verifies [[ -x "$HOME/.claude/bin/<wrapper>.sh" ]] and stops with a clear error if missing. No silent fallback.

Parallelism rule: when two wrappers are independent (design+plan during /trio-build, or the two reviewers during code review), Claude issues both Bash calls in a single tool-use message so the runtime runs them concurrently.

Shared state — .trio/ files

File Written by Read by Required sections
.trio/brief.md /trio-build design wrapper, plan wrapper, reviewers Feature / Success criteria / Constraints
.trio/design-brief.md trio-design.sh ask-gemini.sh (as user prompt) —
.trio/plan-brief.md trio-plan.sh ask-codex.sh (as user prompt) —
.trio/project-context.md user (optional) every wrapper —
.trio/config.json user (optional) (future — not yet consumed) —
.trio/design.md trio-design.sh code, review, orchestrator Summary / Design decisions / Out of scope
.trio/plan.md trio-plan.sh code, review, orchestrator Requirements / Phases
.trio/tests.md trio-plan.sh code, review Acceptance tests / Edge cases
.trio/_plan-raw.md.last trio-plan.sh user (debug only) —
.trio/implementation/SUMMARY.md Claude (code) review wrappers, /trio-finalize per-task entries + Final status
.trio/review-gemini.md trio-review.sh gemini /trio-finalize Verdict line
.trio/review-gpt.md trio-review.sh codex /trio-finalize Verdict line
.trio/blockers.md Claude (code) user, orchestrator — (only written when implementation blocks)

Review filename rule: the two review files are review-gemini.md and review-gpt.md. The GPT file uses the vendor-neutral name "gpt" even though the wrapper argument is codex. If you see review.md (singular) in any prompt or doc, that is a bug.

Skill → command mapping

Skill File Invoked by
trio-orchestrate skills/trio-orchestrate/SKILL.md /trio-build, /trio-continue, /trio-finalize, /trio-test
trio-design skills/trio-design/SKILL.md ask-gemini.sh (used as system prompt by trio-design.sh)
trio-plan skills/trio-plan/SKILL.md ask-codex.sh (used as system prompt by trio-plan.sh)
trio-code skills/trio-code/SKILL.md /trio-code, /trio-continue
trio-review skills/trio-review/SKILL.md ask-gemini.sh and ask-codex.sh (used as system prompt by trio-review.sh)

Install / uninstall contract

  • install.sh and install.ps1 both write install-manifest.json inside the plugin directory recording every link they create. Gitignored.
  • uninstall.sh and uninstall.ps1 remove only entries from the manifest, and only if the entry still resolves to a symlink pointing into the plugin directory (or, in Windows copy mode, is byte-identical to the plugin source).
  • Neither installer overwrites a pre-existing non-link file. Conflicts are printed and left to the user.
  • ~/.claude/bin/*.sh wrappers are not managed by this plugin's installer — the user installs them (see INSTALL.md §1). The plugin ships one template (templates/trio-review.sh.template) which the user copies into ~/.claude/bin/trio-review.sh.

When you change the contract

  1. Edit this file first.
  2. Update commands/ and skills/*/SKILL.md to match.
  3. Update README.md and INSTALL.md.
  4. Update templates/trio-review.sh.template if the review flow changes.
  5. Run bash scripts/smoke-test.sh — it must exit 0.