jason/cowork-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add mode-document reference v1.0

Browse Source
This commit is contained in:
jason
2026-05-05 11:27:28 -05:00
parent 41b567a435
commit be67cd4b8e
1 changed files with 311 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/cowork-project/references/mode-document.md
+311
View File
@@ -0,0 +1,311 @@
# 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:
```bash
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
```markdown
# [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:
```bash
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:
```bash
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.).