Coware — Shared Living Specs

Coware keeps AI agents aligned by syncing shared interface specs across your team. Every agent reads the same spec before writing code — no more merge conflicts from mismatched APIs, field names, or return types.

FIRST: Check initialization status

Check if

.coware/config.json

exists in the project root.

---

IF

.coware/config.json

EXISTS → Project is initialized

This project already uses Coware. Follow this workflow:

Before coding

1. Run:

   node .coware/pull.mjs

   • This fetches the latest specs from the Coware server.
   • If the command fails (network error, server down), proceed with whatever local

     .coware/specs/*.md

     files exist.
2. Read ALL

   .md

   files in

   .coware/specs/

   .
   • These specs are the source of truth for all interfaces, types, API contracts, and data shapes in this project.
3. You are ready to code. Follow the specs exactly.

While coding

• Follow specs exactly. Match field names, types, return formats, status codes.
• If a spec needs to change (new endpoint, renamed field, etc.):
  1. Update the relevant

     .coware/specs/<slug>.md

     file FIRST.
  2. Run:

     node .coware/sync.mjs

  3. THEN update the code to match.
  4. Never let code drift from specs.

After coding

1. If you created or modified any spec files, run:

   node .coware/sync.mjs

   • This pushes updated specs to the server so teammates get them.
   • If sync fails, the local spec files are still the source of truth.
2. If you did NOT change any specs, no action needed.

---

IF

.coware/config.json

DOES NOT EXIST → New project setup

This project has not been initialized with Coware yet.

Setup instructions

1. Fetch the setup guide:

   https://coware.team/llms.txt

2. Read the response carefully.
3. Follow ALL instructions in the guide from start to finish, in order.
   • The guide will walk you through: login, project creation/joining, file setup, and spec generation.
   • Execute ALL steps in ONE go. Do NOT stop to ask the user questions mid-flow.
   • The ONLY acceptable way to ask the user something is via a tool-based selection dialog. NEVER stop your turn to ask via text.
4. After setup completes, follow the "Project is initialized" workflow above.

---

Harness — Automatic Feedback System

When this skill is active, the following happens automatically without any manual action required:

Session start (SessionStart hook)

Latest specs are pulled from the Coware server. You receive a summary of all available specs. If the server is unreachable, local specs are used.

After every code edit (PostToolUse hook)

Each time you modify a file, two checks run:

1. Identifier scan: Checks if the modified file relates to any spec-defined interfaces, types, or routes. If yes, injects a warning into your context.
2. Semantic check: You self-verify whether the change still conforms to the relevant spec definitions.

Before task completion (Stop hook)

When you attempt to finish a task, two gates must pass:

1. Sync check: Verifies no teammates have pushed spec changes you haven't pulled, and you haven't left local spec edits unsynced. If either fails, you are blocked from finishing until resolved.
2. Compliance review: An agent reviews all code changes against specs and blocks completion if any interface mismatches are found.

---

You are inside a Harness

You operate within a Guides × Sensors feedback loop:

• Guides (before you act): Spec files tell you what interfaces look like. Read them FIRST. They reduce your error rate on the first attempt.
• Sensors (after you act): Hooks validate your output. If you ignore the Guides, the Sensors will catch it and you'll have to fix it anyway.

Investing time in reading specs (Guides) saves token cost from failed Sensor checks. The more thoroughly you read specs, the fewer corrections needed.

---

Critical Rule: One feature at a time

• NEVER implement multiple features in parallel
• Complete one feature → verify against spec → sync → THEN start the next
• If the task has multiple parts, break it into sequential steps
• Each step must pass the Stop hook verification before moving on
• This prevents "big bang" integration failures

---

Shift Left: Catch errors early

• Read specs BEFORE coding (cheapest fix — just read)
• Check types DURING coding (medium cost — fix before commit)
• Don't rely on Stop hook to catch everything (expensive — redo work)

The Stop hook is your safety net, not your primary quality tool. Your primary quality tool is reading the spec first.

---

Recommended Workflow

For best results, follow this structured approach:

1. Understand (before coding)

• Pull latest specs:

  node .coware/pull.mjs

• Read every spec in

  .coware/specs/

• Identify which specs relate to your task
• Note which interfaces you'll use vs. which you might need to change

2. Plan

• For interfaces you'll use: plan implementation that matches the spec exactly
• For interfaces you'll change: plan to update the spec first, sync, then code
• If unsure whether a change is needed, read the spec again
• Break multi-feature tasks into sequential steps (one feature at a time)

3. Implement (one feature at a time)

• Code following spec constraints (the PostToolUse hook will warn you if you drift)
• If you need to change a shared interface:
  1. STOP coding
  2. Edit

     .coware/specs/<slug>.md

  3. Run

     node .coware/sync.mjs

  4. Continue coding
• Complete and verify one feature before starting the next

4. Verify

• The Stop hook automatically checks compliance before you can finish
• If blocked: read the reason, fix the issue, and the check will re-run

---

Long tasks: Reset over compress

For tasks that approach context limits:

• Commit work in progress with descriptive messages
• Update

  .coware/specs/

  with any interface changes
• Run

  node .coware/sync.mjs

• Let the context reset — the next session will pull fresh specs
• Git log + specs = complete handoff to the next session

Context reset with structured handoff beats context compression.

---

After completing work

If you learned something non-obvious during this task (a gotcha, a pattern, a constraint not captured in specs), consider:

1. Updating the relevant spec file to capture it
2. Running

   node .coware/sync.mjs

   so teammates benefit

Specs that grow with usage become more valuable over time.

---

Spec file format

Each spec file in

.coware/specs/

is a Markdown file:

# Module Name

## Endpoints

### GET /api/resource
- Response: `{ data: Resource[], total: number }`
- Auth: Bearer token required

## Types

### Resource
- id: string (UUID)
- name: string
- createdAt: string (ISO 8601)

When generating or updating specs, follow this structure:

• One file per module/domain (e.g.,

  auth.md

  ,

  users.md

  ,

  orders.md

  )
• Include endpoints with method, path, request/response shapes
• Include shared types and enums
• Include auth requirements and error formats
• Use consistent naming conventions throughout all specs

Inviting teammates

After setup, share the invite code (found in

.coware/config.json

→

invite

field) with teammates. They install this skill and run

/coware

— their agent will automatically join the project and pull shared specs.

Troubleshooting

• pull.mjs fails: Proceed with local

  .coware/specs/*.md

  files.
• sync.mjs fails: Local specs are still source of truth. Retry later.
• No specs exist: Scan the codebase and generate specs, then sync.
• Specs conflict with code: Specs win. Update code to match specs, or update specs first if the change is intentional.
• Stop hook blocks you: Read the stderr message — it tells you exactly what to do (pull or sync). Fix it, then the check passes automatically.