refacil-sdd-ai 5.0.3 → 5.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "5.0.3",
+  "version": "5.0.4",
   "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code, Cursor and OpenCode",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"

package/skills/ask/SKILL.md

@@ -38,6 +38,31 @@ Before drafting the `--text`, classify what you are going to ask `@<destination>
 
 If you mix query + change, separate into two messages or make clear which part is read-only and which is versionable work in the other repo.
 
+### Step 1.6: Contract-first framing (recommended)
+
+For cross-repo integrations, prioritize questions that remove ambiguity in **input/output contracts**. A good `ask` usually includes:
+- integration point (endpoint/event/queue and direction)
+- expected input schema/fields and validation rules
+- expected output schema/statuses/errors
+- compatibility/version constraints
+
+This framing increases response quality and reduces back-and-forth.
+
+### Step 1.7: Structured template for integration asks (recommended)
+
+When the question is about cross-repo integration contracts, draft the `--text` using this minimal template:
+
+```text
+integrationPoint: <endpoint/event/queue + direction X->Y or Y->X>
+inputContract: <required/optional fields + key validation rules>
+outputContract: <expected output/status/errors>
+compatibility: <version/flags/env constraints or "unknown">
+sourceOfTruthRequest: <where to confirm in destination repo>
+question: <concrete doubt to resolve>
+```
+
+If some fields are unknown, send `unknown` explicitly — do not invent values.
+
 ### Step 2: Decide whether to use `--wait`
 
 Two modes:
@@ -65,6 +90,7 @@ Use `Bash` with the chosen command.
 ### Step 4: Process result
 
 - If `--wait` brought a response: use it as context to continue your work; do not just report the message, continue with the flow the user asked for.
+- If the response is partial or ambiguous: send a **retry ask** in the same thread, reusing the template fields that remain unresolved.
 - If `--wait` expired: inform the user and propose `/refacil:inbox` to review later.
 - If fire-and-forget: confirm to the user that it was sent.
 
@@ -76,3 +102,4 @@ Use `Bash` with the chosen command.
 - If the destination does not exist in the room, the message is stored in `inbox.jsonl` and will be delivered when they join.
 - If you **agreed** with another session that they will change their repo, they must use **`/refacil:propose`** there and **notify you via bus** when done; if they request changes from you, you do the same here. Full convention: `refacil-prereqs/BUS-CROSS-REPO.md`.
 - **`ask`s that are change requests** must be **substantive in scope** (Step 1.5): the recipient already uses the methodology; do not repeat the guide in the text. Do not use the bus to request opaque quick fixes when the impact requires SDD-AI.
+- For cross-repo contract clarifications, prefer Step 1.7 template. The same structure should also be expected in replies to ease retries.

package/skills/join/SKILL.md

@@ -8,6 +8,15 @@ user-invocable: true
 
 Starts or joins a `refacil-bus` room (local chat room between agents). Argument **$ARGUMENTS** = room name.
 
+## Purpose of joining
+
+Joining a room enables **cross-repo, multi-agent integration work**. The expected use is:
+- consult another repo as source of truth for integration contracts
+- clarify input/output behavior across service boundaries
+- coordinate contract-aligned changes following SDD-AI in each repo
+
+Do not treat the room as general chat. Keep interactions focused on integration uncertainty and ownership.
+
 ## Instructions
 
 ### Step 1: Verify that the presentation block exists in `AGENTS.md`
@@ -73,6 +82,7 @@ Report:
 - Room joined and session name
 - Current members
 - How others can consult this session: `/refacil:ask @<session> "..."`
+- Reminder of scope: use bus messages for cross-repo contract clarification (inputs/outputs, events, compatibility), not generic conversation.
 
 ## Rules
 

package/skills/prereqs/BUS-CROSS-REPO.md

@@ -2,12 +2,32 @@
 
 Shared protocol for all skills that may need context from another repository during execution (`explore`, `propose`, `verify`, `bug`).
 
+## Primary objective (non-negotiable)
+
+The bus is not a generic chat channel. Its primary purpose is **cross-repo and multi-agent integration clarity**:
+
+- Clarify **input/output contracts** between services (request payloads, response schemas, events, queues, headers, status/error semantics).
+- Resolve uncertainty when a flow in this repo depends on behavior implemented in another repo.
+- Coordinate implementation ownership when a contract mismatch is found.
+
+If a bus conversation does not improve integration certainty, it is probably off-scope.
+
 ## When to apply
 
 Each skill defines its own trigger (see its `SKILL.md`). In general, apply when the skill detects that **it needs information that does not live in this repo** and assuming it would risk an error: API contracts, event formats, consumer/producer behavior, shared queues.
 
 **Golden rule**: the bus is **optional and non-blocking**. Do not invoke it if the question can be answered by reading this repo's code, or if there is no real cross-repo uncertainty. If the dev answers or clarifies the doubt directly (verbally, via chat, with a link to docs, etc.), **the skill continues normally** — the bus is only one of the possible ways to resolve the unknown.
 
+### Typical trigger in microservice architectures
+
+If repository **X** calls or consumes service **Y** but **Y** lives in another repo, and this repo cannot validate the real contract or behavior by itself, use the bus to consult the agent in **Y**.
+
+This includes:
+- endpoint signatures and field semantics
+- event payload versions and compatibility
+- producer/consumer assumptions not documented in the current repo
+- acceptance/rejection behavior for invalid input
+
 ## Protocol (3 steps)
 
 When the skill's trigger is met:
@@ -20,6 +40,41 @@ When the skill's trigger is met:
 
 If the user does not know the bus or does not know how to configure it, refer them to `/refacil:guide` (section "Bus between agents") before attempting the consultation.
 
+### Message quality for high-impact answers
+
+When asking through the bus, frame questions around contracts and observable behavior:
+- expected input shape
+- output shape and error modes
+- version/compatibility constraints
+- source-of-truth location in destination repo
+
+Avoid vague requests like "check this integration". Prefer concrete contract questions.
+
+Recommended ask template (integration clarification):
+
+```text
+integrationPoint: <endpoint/event/queue + direction>
+inputContract: <fields + validations>
+outputContract: <outputs/status/errors>
+compatibility: <version/constraints or unknown>
+sourceOfTruthRequest: <where to confirm in destination repo>
+question: <concrete doubt>
+```
+
+Recommended reply template:
+
+```text
+integrationPoint: <confirmed value>
+inputContract: <confirmed value>
+outputContract: <confirmed value>
+compatibility: <confirmed value or unknown>
+sourceOfTruth: <file/path/symbol in destination repo>
+confidence: <high|medium|low>
+openQuestions: <none | unresolved items>
+```
+
+These templates support both first-pass clarification and retry loops.
+
 **Valid output without bus**: at any point in the protocol, if the dev answers or clarifies the doubt directly, record their response as context and **continue with the skill flow**. Do not insist on using the bus or block progress waiting for a cross-repo confirmation the dev already answered through another channel.
 
 ## How to use the response
@@ -31,6 +86,8 @@ Each skill decides what to do with the response:
 - `verify`: incorporate it into the combined report as SUGGESTION; if it reveals a real bug, escalate to WARNING/CRITICAL.
 - `bug`: use it to confirm whether the fix goes in this repo, the other, or both (in which case the other will have its own `/refacil:bug`).
 
+If the response is partial, send a retry `ask` focused only on unresolved `openQuestions`.
+
 ## Room agreements and changes in this repo
 
 An **`ask` whose intent is to request work** (implementation, correction, substantial refactor) in the destination session's repo counts as a **change request**: the text must be **clear in scope** so the destination runs **`/refacil:propose`** (and the usual flow) in **their** repo. **No need** to embed the methodology guide in the message: whoever is in the room already joined via **`/refacil:join`** and the repo follows SDD-AI. Same criterion if the conversation mixes `say` and `ask`. Exception: if the **human user** requests a different procedure.
@@ -53,3 +110,4 @@ By default: **do not close silently** when another session was waiting for the r
 - Do not insist if the dev prefers to resolve it another way (direct reading, docs, verbal question to a colleague).
 - Do not skip `/refacil:propose` (or equivalent user order) for changes agreed in a room that affect this repo without an explicit contrary instruction.
 - Do not **fail to respond via bus** to the requester or the room when you finish a change others were waiting for (see previous section).
+- Do not use the bus for open-ended brainstorming unrelated to cross-repo integration contracts.

package/skills/reply/SKILL.md

@@ -32,11 +32,28 @@ Report to the user that the response was sent.
 - **`reply`**: always when you are responding to something you were asked. This allows the other side in `ask --wait` to unblock automatically.
 - **`say`**: general announcement unrelated to a previous question.
 
+## Contract-focused reply format (for integration questions)
+
+When replying to cross-repo integration clarifications, prefer this structure so the other side can continue without ambiguity:
+
+```text
+integrationPoint: <confirmed endpoint/event/queue + direction>
+inputContract: <confirmed fields/validation>
+outputContract: <confirmed outputs/status/errors>
+compatibility: <version/constraints, or "unknown">
+sourceOfTruth: <file/path/symbol in this repo>
+confidence: <high|medium|low>
+openQuestions: <none | list of unresolved points>
+```
+
+If you cannot confirm a field, answer with `unknown` and include the missing evidence in `openQuestions`.
+
 ## Rules
 
 - If you just **implemented** a change requested by another agent and this `reply` is the **close** (done / PR / blocked), include that summary in the text; it is the default channel to respond to whoever made the original `ask` (same thread).
 - Correctly quote the text.
 - Respond only from your knowledge of THIS repo. If the question falls outside your scope, say it explicitly: `"out of my scope, repo X knows about this"`.
+- If your reply leaves unresolved contract points, explicitly list them so the asker can send a targeted retry `ask`.
 - If there is no pending question directed to you and you do not want to link it, use `/refacil:say` instead.
 - If you were asked multiple questions and want to respond to a specific older one, pass `--correlation <id>` explicitly:
   ```bash

package/templates/methodology-guide.md

@@ -29,6 +29,8 @@ Skills are identical in `.claude/skills/refacil-*/` (Claude Code) and `.cursor/s
 
 Local plain-text channel between Claude Code / Cursor sessions running in different repos. Prevents the developer from manually transcribing context between their own agents.
 
+Primary intent: **cross-repo integration clarity**. Use it to clarify service **input/output contracts** (APIs, events, queues, compatibility, errors) when the source of truth is in another repo.
+
 | Command | Description |
 |---------|-------------|
 | `/refacil:join <room>` | Create or join a room. First time generates an introduction block in `AGENTS.md`. |
@@ -40,6 +42,8 @@ Local plain-text channel between Claude Code / Cursor sessions running in differ
 
 Typical usage: before starting a task that may require context from other repos, the developer puts the agent in each other repo into `/refacil:attend`. Then, in their working repo, the LLM can request context with `/refacil:ask @<repo> "..." --wait` and receive the response automatically without the developer switching between windows.
 
+In microservice setups (repo X depends on repo Y), use the bus when X cannot validate Y's real behavior from local code alone. Keep questions contract-focused and explicit.
+
 If changes affecting a repo are agreed upon in the room, the SDD-AI flow (`/refacil:propose`, etc.) is followed in that repo and the implementer **notifies via the bus** when done (details in `refacil-prereqs/BUS-CROSS-REPO.md` in the package). **`ask` requests that involve work** in another repo must include **clear scope**; the destination uses **`/refacil:propose`** by convention. See skill `/refacil:ask`.
 
 Useful CLI for the developer: `refacil-sdd-ai bus view` (opens web UI in browser), `bus watch <session>` (terminal panel), `bus status`, `bus rooms`. These do not consume tokens.