teamshare-bridge 0.22.5 → 0.22.7

package/skills/teamshare-cdd/SKILL.md

@@ -1,206 +1,206 @@
----
-name: teamshare-cdd
-description: Documents-driven development for TeamShare. Before any code, find and read the project's documents in the Documents tab (virtual folders: docs/, agents/<you>/tasks/<taskId>/). Write plan.md BEFORE starting, keep progress.md/notes updated while working (update_document_note), and close with summary.md. Uploads and markdown notes live in Cloudinary-backed virtual folders, never loose files.
----
-
-# TeamShare Documents-Driven Development (CDD)
-
-You are working a task in a TeamShare project. In TeamShare, **the project's
-Documents tab is the source of truth** — the same way `docs/` + `AGENTS.md`
-drive TeamShare's own development at the repo root. Documents are organized
-in **virtual folders** (a lowercase path stored on each document; the UI
-renders them as a tree). Your job is to work from the docs, write the docs,
-and leave the task better documented than you found it.
-
-## The document library convention
-
-Every project document carries a `folderPath` (lowercase kebab segments, `/`
-= root, max 8 levels). The folders an agent creates MUST follow this layout:
-
-```
-docs/                              <- shared, project-wide knowledge
-├── contracts/                     <- API/endpoint contract notes
-├── adr/                           <- ADR-<n>-<title>.md architecture decisions
-└── guides/                        <- how-to guides for humans + agents
-agents/
-└── <agent-slug>/                  <- ONE folder per agent (short, stable slug)
-    └── tasks/
-        └── <taskId>/              <- per-task workspace
-            ├── plan.md            <- written BEFORE starting the work
-            ├── progress.md        <- updated while working (or rely on subtasks)
-            └── summary.md         <- written on completion
-reports/                           <- milestone reports (optional)
-```
-
-Rules that are not optional:
-
-- **Kebab-case** document names ending in `.md` (`.markdown`/`.txt` ok).
-- **Lowercase** folder paths; no spaces, no leading/trailing slashes.
-- **One folder per agent, one subfolder per task.** Never write outside your
-  own folder except into `docs/**` when you add shared knowledge.
-- Document names are unique enough to be obvious (`plan.md`, `progress.md`,
-  `summary.md`, `adr-001-auth-rbac.md`).
-
-## The workflow — three gates
-
-### START (before touching any code)
-1. **Read the cloud project context** via `get_project_context` — the
-   structured AGENTS.md every agent maintains (overview, architecture,
-   structure, workflows, conventions, gotchas). This is your map of the
-   codebase; it tells you where things live BEFORE you explore.
-   **Section-granular reads:** pass `sections: ["..."]` and fetch ONLY what
-   you need for this task (e.g. `["conventions","gotchas"]`) — never pull the
-   whole document to read one section. Omit `sections` only when you
-   genuinely need everything.
-2. `list_document_folders` + `list_documents` for the project.
-3. Read `docs/contracts`, `docs/adr`, `docs/guides` that exist — they govern
-   your implementation (same way `docs/api-contract.md` and
-   `docs/ui-style-guide.md` govern TeamShare's repos).
-4. Read your own task folder if this is a `--continue`/resumed session.
-5. **Write `plan.md` FIRST** via `create_document`: goal, decisions, files to
-   touch, step list. No code until the plan note exists.
-6. **Move the task to `in_progress`** via `update_task` — you are now working it.
-
-### DO (while working)
-7. Check off subtasks (`update_subtask done: true`) and update
-   `progress.md`/`plan.md` via `update_document_note` as you go — the human
-   watches the app.
-8. **Checklist items — ALWAYS list first.** Before creating checklist items,
-   call `list_checklist_items` (pass `taskId` or `subtaskId`) to see what
-   already exists. Use `update_checklist_item` with the existing ID to toggle
-   done/rename — do NOT create duplicates. Only call `create_checklist_item`
-   for genuinely new items. The `get_task` response also includes
-   `checklistItems` for task-level items, and `list_subtasks` includes them
-   per subtask.
-9. When you make an architecture decision worth keeping, add it to `docs/adr`
-   as `ADR-<n>-<title>.md` (short: context → decision → consequences).
-10. Blocked? Use `ask_human` and include a pointer to the relevant note.
-
-### DONE (before closing)
-11. **Move the task to `in_review`** via `update_task` — signals the human
-    to review your work.
-12. Write `summary.md`: what you built, why, how it maps to the plan, links to
-    related docs, follow-ups.
-13. Post the closing comment referencing the summary doc.
-14. Never leave a task without `plan.md` + `summary.md` notes.
-15. **Git is the runner's job.** After your session the bridge automatically
-    commits everything in the working tree on branch
-    `teamshare/<taskId8>`, pushes it and opens a pull request — so do NOT
-    run git commit/branch/push yourself and never leave work outside the
-    linked folder; just save your files before finishing. The closing
-    comment reports the commit/push/PR outcome (or why it was skipped).
-
-    **CRITICAL: Multi-repo structure.** TeamShare is NOT a single git repo at the
-    root. Each app folder (`frontend/`, `teamshare-backend/`, `teamshare-mobile-app/`,
-    `teamshare-bridge/`) is its own independent git repository. The root directory is
-    NOT a git repository. Running `git add`, `git commit`, or `git push` from the root
-    will fail with "not a git repository" errors. See `docs/agent-guides/multi-repo-git.md`
-    for the complete workflow.
-16. **Update the project context when reality changed** (mandatory). If your
-    work added/moved/deleted folders or files that matter, changed commands or
-    workflows, or established new conventions — call `update_project_context`
-    with ONLY the section(s) you actually changed and `append: true`, sending
-    just your addition as the value (`structure`, `workflows`, `conventions`,
-    `architecture`, `gotchas`). **Section-granular writes:** the backend
-    merges your addition into the existing section server-side — never
-    re-send untouched or pre-merged section text, and never re-send whole
-    sections you only appended to. `append` needs no `baseVersion`; a full
-    replace still does. BEFORE resolving a task, reflect the soft sections:
-    call `reflect_context` with the `overview`/`architecture`/`conventions`/
-    `gotchas` additions you decided are durable (you are the AI that decides —
-    no other model runs on the hub; `update_project_context` handles the
-    structural `structure`/`workflows` sections). Review `gotchas` and
-    `conventions`: anything you learned about this codebase while working
-    (env quirks, patterns that surprised you) belongs there — append those
-    points as new bullets. A stale version on a replace means another writer
-    got there first: re-read via `get_project_context` (with `sections`),
-    merge, retry. Appending past the 60 000-char section cap fails with
-    `SECTION_TOO_LARGE` — split the change instead. The next agent depends on
-    this being accurate — do not leave the map stale.
-
-## Task status progression (guidance)
-
-Status can be set to **any value from any state** — the system allows free
-transitions and reversal. No blocking errors. Use this as a guideline:
-
-```
-open → in_progress → in_review
-```
-
-| When | Set status to | Why |
-|---|---|---|
-| You start working the task | `in_progress` | You claimed it, work has begun |
-| Work is done, ready for human review | `in_review` | Human should review and approve |
-
-**Tip:** Set status as you go. The human sees live progress in the app.
-You can always reverse (e.g. `in_progress` → `open` if you need to reassess).
-Do NOT set `resolved` or `closed` — only humans can approve resolution and close tasks.
-The highest status you may set is `in_review`.
-
-### Claim discipline (hard rule)
-
-If you called `claim_task` on a task, you MUST call `release_task` for it
-before your session ends — **regardless of the task's status** (even when
-it stays `open` or `in_progress` for someone else to review). An unreleased
-claim blocks every other agent from touching that task for the whole
-30-minute lease. The bridge also auto-releases all claims made by your
-session at exit, but never rely on that: release explicitly as soon as
-your work is done.
-
-## Build mode (IMP-700) — the project's workflow engine
-
-Some projects run **build mode**: the project has a build agent, and tasks
-marked **ready for dev** (`readyForDev: true`) form an ordered build queue
-(`sortOrder` asc, `createdAt` asc) that the agent works **strictly one at a
-time, fully completing each**. When you are working a task as part of a build
-run, the following rules apply ON TOP of everything above:
-
-- **Ready for dev is the gate.** A task stays out of the build queue until a
-  human (or the planner) sets `readyForDev: true`. The queue only contains
-  `readyForDev=true AND status=open` tasks (plus blocked in-progress ones).
-- **Strict order, full completion.** Work the queue in exact order — never
-  pick a later task while an earlier one is open. Do not move on until the
-  current task is genuinely complete: build passes, `plan.md` written first,
-  subtasks checked off, `summary.md` written, status moved to `in_review`.
-- **Failure protocol (never block the queue).** If a task cannot be finished,
-  the BUILD LOOP (not you) handles it: it leaves a `[question]` comment on the
-  task (marked with the literal prefix `[question]`) and a message in the
-  project's `#agent-questions` channel, then continues with the next ready
-  task. When a human answers, the loop resumes the skipped task automatically.
-- **Planning (`--draft`).** When the human asks you to plan a build run from a
-  goal, create the tasks yourself with `create_task`:
-  - `readyForDev: true` so they enter the queue,
-  - increasing `sortOrder` (1, 2, 3, ...) so they are worked strictly in order,
-  - dependencies first (a task that unblocks others comes before them),
-  - write the plan into `agents/<your-slug>/tasks/<taskId>/plan.md` per task,
-    and a shared `docs/guides/build-plan.md` note summarizing the order.
-- **Progress signals.** Push the task to `in_progress` when you start it and
-  `in_review` when done — the build loop watches status to decide
-  done vs. failed, so a task left in `in_progress` at the end of a session is
-  treated as failed and skipped.
-
-## Tools to use
-
-- `get_project_context <projectId>` — the cloud AGENTS.md (+ version). Pass
-  `sections: ["conventions","gotchas", …]` to fetch ONLY what you need.
-- `update_project_context` — section-granular write: send ONLY the section(s)
-  you changed with `append: true` (your addition only — the backend merges it;
-  no `baseVersion` needed). Full replace still needs `baseVersion` (409 =
-  re-read + merge). Never re-send untouched sections.
-- `list_document_folders <projectId>` — the tree, with per-folder counts.
-- `list_documents <projectId>` — files (optionally filter by folder).
-- `read_document <documentId>` — content (notes return their markdown body).
-- `create_document` — write a note (`name`, `content`, `folderPath`).
-- `update_document_note <documentId> <content>` — replace a note's body.
-- Uploads (PDFs, images, binaries) are Cloudinary-hosted into
-  `documents/<folderPath>` and recorded as file documents — mirror the same
-  folder convention.
-
-## References
-
-- `docs/agent-tasks/agent-hub-connection.md` — the agent contract.
-- `docs/api-contract.md` — response envelope, pagination, type mirroring.
-- TeamShare root `docs/` + `IMPLEMENTATION_TRACKER.md` — the convention this
-  skill mirrors.
-- Backend: `GET /documents/folders`, `POST /documents/note`,
+---
+name: teamshare-cdd
+description: Documents-driven development for TeamShare. Before any code, find and read the project's documents in the Documents tab (virtual folders: docs/, agents/<you>/tasks/<taskId>/). Write plan.md BEFORE starting, keep progress.md/notes updated while working (update_document_note), and close with summary.md. Uploads and markdown notes live in Cloudinary-backed virtual folders, never loose files.
+---
+
+# TeamShare Documents-Driven Development (CDD)
+
+You are working a task in a TeamShare project. In TeamShare, **the project's
+Documents tab is the source of truth** — the same way `docs/` + `AGENTS.md`
+drive TeamShare's own development at the repo root. Documents are organized
+in **virtual folders** (a lowercase path stored on each document; the UI
+renders them as a tree). Your job is to work from the docs, write the docs,
+and leave the task better documented than you found it.
+
+## The document library convention
+
+Every project document carries a `folderPath` (lowercase kebab segments, `/`
+= root, max 8 levels). The folders an agent creates MUST follow this layout:
+
+```
+docs/                              <- shared, project-wide knowledge
+├── contracts/                     <- API/endpoint contract notes
+├── adr/                           <- ADR-<n>-<title>.md architecture decisions
+└── guides/                        <- how-to guides for humans + agents
+agents/
+└── <agent-slug>/                  <- ONE folder per agent (short, stable slug)
+    └── tasks/
+        └── <taskId>/              <- per-task workspace
+            ├── plan.md            <- written BEFORE starting the work
+            ├── progress.md        <- updated while working (or rely on subtasks)
+            └── summary.md         <- written on completion
+reports/                           <- milestone reports (optional)
+```
+
+Rules that are not optional:
+
+- **Kebab-case** document names ending in `.md` (`.markdown`/`.txt` ok).
+- **Lowercase** folder paths; no spaces, no leading/trailing slashes.
+- **One folder per agent, one subfolder per task.** Never write outside your
+  own folder except into `docs/**` when you add shared knowledge.
+- Document names are unique enough to be obvious (`plan.md`, `progress.md`,
+  `summary.md`, `adr-001-auth-rbac.md`).
+
+## The workflow — three gates
+
+### START (before touching any code)
+1. **Read the cloud project context** via `get_project_context` — the
+   structured AGENTS.md every agent maintains (overview, architecture,
+   structure, workflows, conventions, gotchas). This is your map of the
+   codebase; it tells you where things live BEFORE you explore.
+   **Section-granular reads:** pass `sections: ["..."]` and fetch ONLY what
+   you need for this task (e.g. `["conventions","gotchas"]`) — never pull the
+   whole document to read one section. Omit `sections` only when you
+   genuinely need everything.
+2. `list_document_folders` + `list_documents` for the project.
+3. Read `docs/contracts`, `docs/adr`, `docs/guides` that exist — they govern
+   your implementation (same way `docs/api-contract.md` and
+   `docs/ui-style-guide.md` govern TeamShare's repos).
+4. Read your own task folder if this is a `--continue`/resumed session.
+5. **Write `plan.md` FIRST** via `create_document`: goal, decisions, files to
+   touch, step list. No code until the plan note exists.
+6. **Move the task to `in_progress`** via `update_task` — you are now working it.
+
+### DO (while working)
+7. Check off subtasks (`update_subtask done: true`) and update
+   `progress.md`/`plan.md` via `update_document_note` as you go — the human
+   watches the app.
+8. **Checklist items — ALWAYS list first.** Before creating checklist items,
+   call `list_checklist_items` (pass `taskId` or `subtaskId`) to see what
+   already exists. Use `update_checklist_item` with the existing ID to toggle
+   done/rename — do NOT create duplicates. Only call `create_checklist_item`
+   for genuinely new items. The `get_task` response also includes
+   `checklistItems` for task-level items, and `list_subtasks` includes them
+   per subtask.
+9. When you make an architecture decision worth keeping, add it to `docs/adr`
+   as `ADR-<n>-<title>.md` (short: context → decision → consequences).
+10. Blocked? Use `ask_human` and include a pointer to the relevant note.
+
+### DONE (before closing)
+11. **Move the task to `in_review`** via `update_task` — signals the human
+    to review your work.
+12. Write `summary.md`: what you built, why, how it maps to the plan, links to
+    related docs, follow-ups.
+13. Post the closing comment referencing the summary doc.
+14. Never leave a task without `plan.md` + `summary.md` notes.
+15. **Git is the runner's job.** After your session the bridge automatically
+    commits everything in the working tree on branch
+    `teamshare/<taskId8>`, pushes it and opens a pull request — so do NOT
+    run git commit/branch/push yourself and never leave work outside the
+    linked folder; just save your files before finishing. The closing
+    comment reports the commit/push/PR outcome (or why it was skipped).
+
+    **CRITICAL: Multi-repo structure.** TeamShare is NOT a single git repo at the
+    root. Each app folder (`frontend/`, `teamshare-backend/`, `teamshare-mobile-app/`,
+    `teamshare-bridge/`) is its own independent git repository. The root directory is
+    NOT a git repository. Running `git add`, `git commit`, or `git push` from the root
+    will fail with "not a git repository" errors. See `docs/agent-guides/multi-repo-git.md`
+    for the complete workflow.
+16. **Update the project context when reality changed** (mandatory). If your
+    work added/moved/deleted folders or files that matter, changed commands or
+    workflows, or established new conventions — call `update_project_context`
+    with ONLY the section(s) you actually changed and `append: true`, sending
+    just your addition as the value (`structure`, `workflows`, `conventions`,
+    `architecture`, `gotchas`). **Section-granular writes:** the backend
+    merges your addition into the existing section server-side — never
+    re-send untouched or pre-merged section text, and never re-send whole
+    sections you only appended to. `append` needs no `baseVersion`; a full
+    replace still does. BEFORE resolving a task, reflect the soft sections:
+    call `reflect_context` with the `overview`/`architecture`/`conventions`/
+    `gotchas` additions you decided are durable (you are the AI that decides —
+    no other model runs on the hub; `update_project_context` handles the
+    structural `structure`/`workflows` sections). Review `gotchas` and
+    `conventions`: anything you learned about this codebase while working
+    (env quirks, patterns that surprised you) belongs there — append those
+    points as new bullets. A stale version on a replace means another writer
+    got there first: re-read via `get_project_context` (with `sections`),
+    merge, retry. Appending past the 60 000-char section cap fails with
+    `SECTION_TOO_LARGE` — split the change instead. The next agent depends on
+    this being accurate — do not leave the map stale.
+
+## Task status progression (guidance)
+
+Status can be set to **any value from any state** — the system allows free
+transitions and reversal. No blocking errors. Use this as a guideline:
+
+```
+open → in_progress → in_review
+```
+
+| When | Set status to | Why |
+|---|---|---|
+| You start working the task | `in_progress` | You claimed it, work has begun |
+| Work is done, ready for human review | `in_review` | Human should review and approve |
+
+**Tip:** Set status as you go. The human sees live progress in the app.
+You can always reverse (e.g. `in_progress` → `open` if you need to reassess).
+Do NOT set `resolved` or `closed` — only humans can approve resolution and close tasks.
+The highest status you may set is `in_review`.
+
+### Claim discipline (hard rule)
+
+If you called `claim_task` on a task, you MUST call `release_task` for it
+before your session ends — **regardless of the task's status** (even when
+it stays `open` or `in_progress` for someone else to review). An unreleased
+claim blocks every other agent from touching that task for the whole
+30-minute lease. The bridge also auto-releases all claims made by your
+session at exit, but never rely on that: release explicitly as soon as
+your work is done.
+
+## Build mode (IMP-700) — the project's workflow engine
+
+Some projects run **build mode**: the project has a build agent, and tasks
+marked **ready for dev** (`readyForDev: true`) form an ordered build queue
+(`sortOrder` asc, `createdAt` asc) that the agent works **strictly one at a
+time, fully completing each**. When you are working a task as part of a build
+run, the following rules apply ON TOP of everything above:
+
+- **Ready for dev is the gate.** A task stays out of the build queue until a
+  human (or the planner) sets `readyForDev: true`. The queue only contains
+  `readyForDev=true AND status=open` tasks (plus blocked in-progress ones).
+- **Strict order, full completion.** Work the queue in exact order — never
+  pick a later task while an earlier one is open. Do not move on until the
+  current task is genuinely complete: build passes, `plan.md` written first,
+  subtasks checked off, `summary.md` written, status moved to `in_review`.
+- **Failure protocol (never block the queue).** If a task cannot be finished,
+  the BUILD LOOP (not you) handles it: it leaves a `[question]` comment on the
+  task (marked with the literal prefix `[question]`) and a message in the
+  project's `#agent-questions` channel, then continues with the next ready
+  task. When a human answers, the loop resumes the skipped task automatically.
+- **Planning (`--draft`).** When the human asks you to plan a build run from a
+  goal, create the tasks yourself with `create_task`:
+  - `readyForDev: true` so they enter the queue,
+  - increasing `sortOrder` (1, 2, 3, ...) so they are worked strictly in order,
+  - dependencies first (a task that unblocks others comes before them),
+  - write the plan into `agents/<your-slug>/tasks/<taskId>/plan.md` per task,
+    and a shared `docs/guides/build-plan.md` note summarizing the order.
+- **Progress signals.** Push the task to `in_progress` when you start it and
+  `in_review` when done — the build loop watches status to decide
+  done vs. failed, so a task left in `in_progress` at the end of a session is
+  treated as failed and skipped.
+
+## Tools to use
+
+- `get_project_context <projectId>` — the cloud AGENTS.md (+ version). Pass
+  `sections: ["conventions","gotchas", …]` to fetch ONLY what you need.
+- `update_project_context` — section-granular write: send ONLY the section(s)
+  you changed with `append: true` (your addition only — the backend merges it;
+  no `baseVersion` needed). Full replace still needs `baseVersion` (409 =
+  re-read + merge). Never re-send untouched sections.
+- `list_document_folders <projectId>` — the tree, with per-folder counts.
+- `list_documents <projectId>` — files (optionally filter by folder).
+- `read_document <documentId>` — content (notes return their markdown body).
+- `create_document` — write a note (`name`, `content`, `folderPath`).
+- `update_document_note <documentId> <content>` — replace a note's body.
+- Uploads (PDFs, images, binaries) are Cloudinary-hosted into
+  `documents/<folderPath>` and recorded as file documents — mirror the same
+  folder convention.
+
+## References
+
+- `docs/agent-tasks/agent-hub-connection.md` — the agent contract.
+- `docs/api-contract.md` — response envelope, pagination, type mirroring.
+- TeamShare root `docs/` + `IMPLEMENTATION_TRACKER.md` — the convention this
+  skill mirrors.
+- Backend: `GET /documents/folders`, `POST /documents/note`,
   `PATCH /documents/:id/content`, `GET /documents/:id/raw`.