jason/cowork-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
be67cd4b8e9df5fd1030d6bd12c2e11437381842
cowork-project/skills/cowork-project/references/mode-document.md
T

10 KiB
Raw Blame History

Mode 2 — Document Existing Build

Full step-by-step process for creating or updating coordination artifacts for a built or recently updated CoWork skill, plugin, or tool.

All three primary artifacts — README.md, Wiki doc, and .plugin file (if applicable) — MUST be placed inside the CW-XXX Drive folder before the registry row is written. Verify each one is in the folder. Do not write the registry row until all artifacts that can be created are confirmed in place.

Never write files to the local FUSE-mounted Google Drive path — use Drive API tools only.

Step 1 — Gather Source

Ask the user (skip anything already known from context):

  • Repo URL — the Gitea repo for this project (e.g. https://git.alwisp.com/jason/odoo-mpm-plugin)
  • Plugin file — path to a .plugin file if one was uploaded to this session
  • CW-ID — do you have a specific ID to use, or auto-assign? (follow CW-ID rules in SKILL.md)

If no repo exists, ask: "Would you like me to create a new Git repo for this project?" If yes, use the Gitea MCP create_repo tool to create it now under the appropriate owner. Name it using the project slug (lowercase, hyphenated). Record the URL.

If both a repo URL and a .plugin file are provided:

  • Check the version in both .claude-plugin/plugin.json files
  • Flag any mismatch before continuing
  • Treat the repo as the authoritative source

Step 2 — Extract Metadata

Download the repo archive and extract all key information:

curl -L -o /tmp/plugin-repo.zip "[repo-url]/archive/main.zip"
unzip -o /tmp/plugin-repo.zip -d /tmp/plugin-repo

Read and record:

  • .claude-plugin/plugin.json → name, version, description, author, keywords
  • .mcp.json → server name, command, required env vars (if present — omit for skill-only)
  • skills/[name]/SKILL.md → skill name, trigger phrases, full list of modules and tools, any workflow guidelines, setup instructions embedded in the skill
  • Existing README.md if present (understand what's already there)
  • Any references/ files that describe architecture, data models, or key logic
  • Any assets/ or template files that are part of the skill

The more you read here, the better the wiki and README will be. Don't stop at plugin.json.

Confirm the version number with the user before writing any artifacts.

Step 3 — Determine CW-ID and Registry State

Follow the CW-ID Assignment rules in SKILL.md.

Also read the current registry row if one exists — check whether Drive Folder, Wiki Doc, Repo, and other fields are already populated. Only update fields that changed or are missing.

Step 4 — Create Coordination Folder

Use create_drive_folder to create CW-XXX — [Project Name] under the Coordination folder (parent ID: 1W-FNW--P2R9jVvoowUXFmSe-sAZoY0GS). Record the folder ID.

If a folder already exists (registry row had a Drive Folder link), use that folder. To get its ID from the URL: the ID is the string after /folders/ in the Drive URL.

Step 5 — Write README.md

Generate a thorough README.md using the structure below. Pull every section from the metadata you extracted in Step 2 — don't pad with placeholders when real data exists. A thin README is worse than no README. If the SKILL.md has 12 tools listed, the README should list all 12. If there are workflow guidelines in the skill, summarize them.

README Structure

# [plugin-name]

[One-line description from plugin.json]

**Version:** [version]  
**Author:** [author]  
**Repo:** [repo-url]  
**CoWork Project:** CW-XXX — [Project Name]

---

## Overview
[3–5 sentences: what it does, how it connects, auth model, who uses it, what problem it solves.
Be specific — mention the actual systems, API transport, and credential approach.]

---

## Skills
| Skill | What It Does |
|---|---|
| `skill-name` | [Full description including trigger phrases] |

---

## Tools Reference
[Group tools by module. List every tool — do not abbreviate.]
| Module | Tools |
|---|---|
| **Module Name** | `tool_one`, `tool_two`, `tool_three` |

---

## Setup Instructions
Full install guide: [link to setup doc if available, otherwise omit this line]

**Step-by-step:**
1. [Install step]
2. [Dependency check]
3. [Restart step]
4. [Credential setup]
5. [Verification]

### Setup Checklist
- [ ] [each step as a checkbox]

---

## Connection Details
| Field | Value |
|---|---|
| [Instance/endpoint] | [value] |
| [Transport/protocol] | [value] |
| [Auth method] | [value] |
| [MCP server name] | [value] |

---

## Workflow Notes
[If the SKILL.md contains workflow guidelines, usage patterns, or important caveats,
summarize them here. Don't omit this section if the skill has meaningful operational guidance.]

---

## Requirements
- [Each dependency on its own line with install link if applicable]

---

## Troubleshooting
| Symptom | Fix |
|---|---|
| [Each known issue] | [Fix] |

Upload README.md to Drive: Use create_drive_file with:

  • file_name: README.md
  • folder_id: the CW-XXX folder ID from Step 4
  • mime_type: text/plain
  • content: the full README text

Push README.md to Git repo (if repo exists):

  • Use get_file_contents (owner, repo, ref=main, filePath=README.md) to get existing SHA
  • Use create_or_update_file with the SHA to update, or omit SHA to create fresh
  • Commit message: docs: update README to v[version]

Both destinations are required. Confirm both are written before proceeding.

Step 6 — Package the .plugin File (skip for skill-only with no MCP server)

If the plugin has an MCP server component (has .mcp.json and a server/ directory), build a fresh .plugin package from the downloaded repo archive:

cd /tmp/plugin-repo/[repo-folder-name]
zip -r /tmp/[plugin-name]-v[version].plugin \
  server/[main-script].py \
  .mcp.json \
  .claude-plugin/plugin.json \
  skills/[skill-name]/SKILL.md
# Add any additional skills/ subdirectories if multiple skills exist

For skill-only plugins (no server/ directory, no .mcp.json), package only the skill files:

cd /tmp/plugin-repo/[repo-folder-name]
zip -r /tmp/[plugin-name]-v[version].plugin \
  .claude-plugin/plugin.json \
  skills/
# Include all files under skills/ recursively

Upload to Drive: Use create_drive_file with:

  • file_name: [plugin-name]-v[version].plugin
  • folder_id: the CW-XXX folder ID from Step 4
  • mime_type: application/zip
  • fileUrl: file:///[outputs-path]/[plugin-name]-v[version].plugin

If an older .plugin file exists in the folder, trash it first:

  • Use search_drive_files to find it by name pattern in the folder
  • Use update_drive_file with trashed: true

Step 7 — Create or Update the Wiki Doc

The Wiki uses a 5-section V2 format. Do not use the old 9-section format. A thorough wiki is the goal — the display-catalog wiki is a good benchmark for depth. Read all the skill's reference files before writing so the wiki reflects actual content.

If no Wiki Doc exists for this project:

  1. Use create_doc to create a new Google Doc titled CW-XXX — [Project Name] Wiki
  2. Use update_drive_file to add it to the CW-XXX Drive folder (add_parents: CW-XXX folder ID)
  3. Populate all sections using batch_update_doc

If a Wiki Doc already exists (check registry column N): Read its current content, then update only what changed — typically the Changelog row, and any Skills Exposed entries that were added or modified.

Wiki V2 — Section Content Guidelines

Header block (small text, top of doc): CW-XXX | Status: [status] | Owner: [owner] | Contributors: [contributors] | Last Updated: [date]

1. Concept (3–5 sentences minimum) Describe the problem being solved, how this project solves it, who uses it, and what systems it connects to. Include enough context that someone unfamiliar with the project understands the full picture. Pull from the Concept.md if one exists; expand from there.

2. Skills Exposed (every skill, every trigger phrase) One row per skill. The "What It Does" column should include: what the skill does, what systems it touches, and the key trigger phrases. Don't abbreviate.

Skill Name What It Does
skill-name Full description including trigger phrases and key tools

3. Setup Instructions (complete, actionable) Link to the install guide doc if one exists. Then write a complete inline summary: every step a new team member needs to get from zero to working. Include credential setup, dependencies, restart steps, and verification. Don't just say "see README" — copy the essential steps here so the wiki is self-contained.

Setup Doc: [link or "see README.md in this folder"]

4. Feature Requests & Planning Preserve any existing entries when updating. Seed with placeholders when creating:

# Request Requested By Status
1 [placeholder or real request] [name] Idea

5. Changelog (reverse chronological) Add a new row for every meaningful version change. When creating fresh, seed with the current version. When updating, prepend a new row — do not delete old entries.

Date Version What Changed Who
[today] v[version] [what changed — be specific, e.g. "added three panel families: EXD, LM, LC"] [owner]

Step 8 — Verify All Artifacts Are in the CW-XXX Folder

Before writing the registry row, confirm:

  • README.md is in the Drive folder (check via search_drive_files or confirm upload ID)
  • Wiki doc is in the Drive folder (confirm parent folder ID matches)
  • .plugin file is in the Drive folder (or note "skill-only, no .plugin" explicitly)

If any artifact failed to land in the folder, resolve it before proceeding.

Step 9 — Update the Registry

Write the updated row using the Correct-order insertion rules from SKILL.md.

Fields to always update when documenting an existing build:

  • F (Version): plugin/skill version
  • L (Drive Folder): https://drive.google.com/drive/folders/[folder-id]
  • N (Wiki Doc): Google Doc edit URL
  • Q (Last Updated): today (YYYY-MM-DD)
  • R (Notes): brief specific note about what changed

For new rows, Status = Beta for a first-time documented build. Adjust if the user specifies otherwise.

Step 10 — Confirm to User

Report every artifact with its link:

  • README location: Drive link + Git link (if pushed)
  • .plugin file: Drive link and version (or "skill-only, not applicable")
  • Wiki Doc: Google Doc link
  • Registry: link to sheet

Flag anything that needs manual follow-up (wiki Concept section needs human review, setup doc link placeholder left in, repo URL corrected from what user provided, etc.).

Reference in New Issue View Git Blame Copy Permalink