@simpleapps-com/augur-skills 0.0.1 → 0.0.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SimpleApps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-skills",
-  "version": "0.0.1",
+  "version": "0.0.12",
   "description": "Install curated Claude Code skills",
   "license": "MIT",
   "type": "module",
@@ -11,13 +11,6 @@
     "dist",
     "skills"
   ],
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
-  },
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
@@ -33,5 +26,12 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}

package/skills/simpleapps/claude-code-docs/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: claude-code-docs
+description: Claude Code documentation reference and discovery. Use when looking up Claude Code features, configuration, plugins, skills, hooks, or troubleshooting.
+---
+
+# Claude Code Documentation
+
+## Entry Points
+
+- **Doc index**: https://code.claude.com/docs/llms.txt — fetch first, find relevant page URL, then fetch that page
+- **Full content**: https://code.claude.com/docs/llms-full.txt — large, use when broad context is needed
+
+IMPORTANT: YOU MUST start from `llms.txt` for current URLs. Doc pages are renamed and reorganized with each release — never rely on memorized URLs.

package/skills/simpleapps/conventional-commits/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: conventional-commits
+description: Format all commit messages per the Conventional Commits v1.0.0 spec. Use when creating commits, reviewing commit messages, or discussing git workflow.
+---
+
+# Conventional Commits
+
+Spec: https://www.conventionalcommits.org/en/v1.0.0/
+
+## Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Types
+
+- `feat` — new feature (SemVer MINOR)
+- `fix` — bug fix (SemVer PATCH)
+- Also permitted: `build`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test`
+
+## Rules
+
+- Scope is optional, in parentheses: `feat(parser):`
+- Description MUST immediately follow the colon and space
+- Body is optional, separated by one blank line from description
+- Footers are optional, separated by one blank line from body
+- Breaking changes: add `!` before colon OR use `BREAKING CHANGE:` footer (SemVer MAJOR)
+- `BREAKING CHANGE` MUST be uppercase
+- Footer tokens use hyphens for spaces (e.g., `Acked-by`)

package/skills/simpleapps/fyxer/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: fyxer
+description: Fyxer AI meeting recording integration. Covers extraction, local caching, and posting to downstream services. Use when processing Fyxer recordings or meeting transcripts.
+---
+
+# Fyxer
+
+Fyxer AI records and summarizes meetings. This skill covers extracting data from Fyxer and routing it to other services.
+
+## Fyxer URLs
+
+Recording page: `https://app.fyxer.com/call-recordings/<meeting-uuid>:<calendar-event-id>`
+
+The URL path after `/call-recordings/` contains two parts separated by a colon:
+- **Meeting UUID** (before colon): `52f0cf2b-fdb8-4e95-8b01-2afb6d367c69`
+- **Calendar event ID** (after colon): `2fg5k3v3hffl91dnuqauc15suk_20260119T190000Z`
+
+Use only the **meeting UUID** for cache folders, duplicate checks, and frontmatter.
+
+Each recording has two tabs:
+- **Summary** — AI-generated summary with section headings, participants, action items. Has "Copy summary" and "Download PDF" buttons.
+- **Transcript** — Speaker-attributed, timestamped full transcript. Has "Copy transcript" and "Download transcript" buttons.
+
+## Local Cache
+
+All extracted data is cached at `~/.simpleapps/fyxer/<meeting-uuid>/`:
+
+```
+summary.txt     - raw Fyxer summary (from Summary tab)
+transcript.txt  - raw Fyxer transcript (from Transcript tab)
+message.txt     - assembled output (generated by downstream processes, e.g. basecamp.md)
+```
+
+Cache is populated via Chrome extraction (see below) and reused across processes.
+
+## Chrome Extraction
+
+Only needed when local cache files are missing.
+
+### Extract transcript
+
+Click the **Transcript** tab. Extraction methods (in order of preference):
+
+1. **"Download transcript" button** (BEST) — Downloads a `.txt` file to `~/Downloads/`. Complete content, no truncation. Copy to cache dir, then delete the download.
+2. **"Copy transcript" button** + `pbpaste` — Copies to system clipboard. Write to disk: `pbpaste > transcript.txt`. Reliable but requires clipboard access.
+3. **`get_page_text`** — UNRELIABLE. Only captures visible/partial content. Missed most of a 30-minute transcript in testing. DO NOT USE for transcripts.
+
+Save to `~/.simpleapps/fyxer/<meeting-uuid>/transcript.txt`.
+
+### Extract summary
+
+The Summary tab is the default view. Extraction methods (in order of preference):
+
+1. **"Copy summary" button** + `pbpaste` (BEST) — Copies markdown to clipboard. Write to disk: `pbpaste > summary.txt`. Summaries are short (~1,700 chars) so this works well.
+2. **`get_page_text`** — Works for short summaries but mixes in page chrome. Not recommended.
+
+Save to `~/.simpleapps/fyxer/<meeting-uuid>/summary.txt`.
+
+### Extract participants
+
+Click the **participant count dropdown** (e.g. "3 participants") in the page header to reveal attendee names and emails. Take a screenshot to read them.
+
+### Clipboard verification
+
+To verify clipboard content is complete before writing to disk:
+
+```javascript
+(async () => {
+  const text = await navigator.clipboard.readText();
+  window.__temp = text;
+  return JSON.stringify({
+    length: text.length,
+    first50: text.substring(0, 50),
+    last100: text.substring(text.length - 100)
+  });
+})()
+```
+
+Then write and verify: `pbpaste > target.txt && wc -c target.txt`
+
+**Note**: Do NOT try to read full clipboard content via JS — Chrome MCP truncates JS output at ~1,000 characters. Always use `pbpaste` to write to disk.
+
+### Download cleanup
+
+MUST clean up `~/Downloads/` after copying downloaded files to the cache directory. Fyxer names downloads like `transcript-SA_USCCO.txt`. Repeated downloads append `(1)`, `(2)`, etc.
+
+## Processes
+
+- See `basecamp.md` for posting meeting transcripts as Basecamp Discussions
+- See `basecamp-index.md` for the Fyxer Index document (duplicate detection, reconciliation)
+
+## Dependencies
+
+- Chrome browser automation (for extraction when cache is empty)

package/skills/simpleapps/fyxer/basecamp-index.md

@@ -0,0 +1,110 @@
+# Fyxer Index — Basecamp Document
+
+Each Basecamp project that receives Fyxer meeting transcripts MUST have a **Fyxer Index** document. This document serves as a fast lookup for duplicate detection and meeting history, accessible to all team members.
+
+## Document Format
+
+- **Title**: `Fyxer Index`
+- **Location**: Documents section of each Basecamp project
+- **Content**: One line per posted meeting, newest first
+
+Each line follows this format:
+
+```
+<meeting-uuid> | <date> | <message-id> | <subject>
+```
+
+Example:
+
+```
+52f0cf2b-fdb8-4e95-8b01-2afb6d367c69 | 2026-01-19 | 514789012 | Fyxer: 2026-01-19
+a1b2c3d4-e5f6-7890-abcd-ef1234567890 | 2026-02-10 | 514801234 | Fyxer: 2026-02-10
+d9e8f7a6-b5c4-3210-fedc-ba0987654321 | 2026-02-15 | 514823456 | Fyxer: 2026-02-15
+```
+
+Fields:
+
+| Field | Source |
+|-------|--------|
+| meeting-uuid | UUID from Fyxer URL (before the colon) |
+| date | Meeting date (YYYY-MM-DD) |
+| message-id | Basecamp message ID returned by `create_message` |
+| subject | Message subject as posted (e.g., `Fyxer: 2026-02-15`) |
+
+## Finding the Index
+
+```
+list_documents(project_id)
+```
+
+Scan for a document titled `Fyxer Index`. Use `get_document(project_id, document_id)` to read its contents.
+
+## Creating the Index
+
+If no `Fyxer Index` document exists in the project, create one before posting the first meeting:
+
+```
+create_document(project_id, "Fyxer Index", "")
+```
+
+This creates an empty document. The first meeting entry will be appended after posting.
+
+## Updating the Index
+
+After successfully posting a meeting transcript via `create_message`, append a new line to the index:
+
+1. Read the current index: `get_document(project_id, document_id)`
+2. Append the new entry to the content (newest first — add to the top)
+3. Update: `update_document(project_id, document_id, title="Fyxer Index", content=updated_content)`
+
+The `create_message` response includes the message ID needed for the index entry.
+
+## Duplicate Check
+
+Before posting a meeting transcript, check the index:
+
+1. Find the Fyxer Index document: `list_documents(project_id)` → scan for `Fyxer Index`
+2. Read it: `get_document(project_id, document_id)`
+3. Search the content for the meeting UUID
+4. If found → the meeting has already been posted. Inform the user and stop.
+5. If not found → safe to proceed with posting.
+
+If no Fyxer Index document exists, there are no posted meetings in this project. Proceed with posting and create the index.
+
+## Reconciliation — Missing Entries
+
+The index MAY fall out of sync if a meeting was posted without updating the index (e.g., manual posting, index creation after existing meetings). To reconcile:
+
+1. List all messages: `list_messages(project_id)`
+2. Filter for messages with `Fyxer:` in the title
+3. For each Fyxer message, call `get_message(project_id, message_id)` and extract the `fyxer-id` from the YAML frontmatter
+4. Compare against the index — add any missing entries
+5. Update the index document with the complete list
+
+Run reconciliation when:
+- The Fyxer Index document is first created in a project that already has Fyxer messages
+- The user suspects the index is incomplete
+- A duplicate check finds nothing but the user believes a meeting was already posted
+
+## Reconciliation — Orphaned Entries
+
+If an index entry references a message that no longer exists (deleted in Basecamp):
+
+1. Attempt `get_message(project_id, message_id)` for the entry
+2. If 404 → the message was deleted. Remove the entry from the index.
+3. Update the index document
+
+Only run orphan cleanup when explicitly requested by the user. Do not automatically delete index entries.
+
+## Updated Posting Process
+
+The full Fyxer → Basecamp posting process (see `basecamp.md`) now includes index management:
+
+1. **Check index** — find Fyxer Index doc, read it, search for meeting UUID
+2. **Check local cache** — if summary.txt and transcript.txt exist, skip extraction
+3. **Extract from Chrome** — if cache is missing (see `SKILL.md`)
+4. **Build message.txt** — frontmatter + transcript
+5. **Post to Basecamp** — `create_message` → capture message_id from response
+6. **Update index** — append new entry to Fyxer Index document (create doc if needed)
+
+Step 6 is new. If the index update fails after a successful post, warn the user — the message is posted but the index is stale. The user can run reconciliation later to fix it.

package/skills/simpleapps/fyxer/basecamp.md

@@ -0,0 +1,91 @@
+# Fyxer → Basecamp
+
+Post Fyxer meeting recordings as searchable Discussions in Basecamp projects.
+
+## Inputs
+
+- **Fyxer recording URL**: `https://app.fyxer.com/call-recordings/<meeting-uuid>:<calendar-event-id>`
+- **Basecamp project ID**: Target project for the Discussion
+
+## Process
+
+### 1. Check for duplicate
+
+Extract the meeting UUID from the Fyxer URL (the part before the colon).
+
+Find the **Fyxer Index** document in the project: `list_documents(project_id)` → scan for title `Fyxer Index`. If found, `get_document(project_id, document_id)` and search the content for the meeting UUID. If the UUID appears, the meeting has already been posted — inform the user and stop.
+
+If no Fyxer Index document exists, there are no tracked meetings in this project. Proceed with posting.
+
+See `basecamp-index.md` for full index format and reconciliation.
+
+### 2. Check local cache
+
+If `~/.simpleapps/fyxer/<meeting-uuid>/summary.txt` and `transcript.txt` both exist, skip to step 3. Otherwise, follow the Chrome extraction steps in `SKILL.md`.
+
+### 3. Build message.txt
+
+Parse `summary.txt` for frontmatter fields, extract participants (see `SKILL.md` participant extraction), and combine with the full transcript from `transcript.txt`:
+
+```
+---
+meeting: SA/ClientName
+date: YYYY-MM-DD
+time: HH:MM-HH:MM
+participants: Person A, Person B, Person C
+topics: Topic One, Topic Two, Topic Three
+fyxer-id: <meeting-uuid>
+---
+
+[contents of transcript.txt]
+```
+
+Frontmatter field sources:
+
+| Field | Source |
+|-------|--------|
+| meeting | Meeting title from the page header |
+| date | Recording date |
+| time | Recording time range |
+| participants | Participant dropdown (click to reveal names) |
+| topics | Section headings from the Summary |
+| fyxer-id | Meeting UUID from the URL (before the colon) |
+
+Save as `~/.simpleapps/fyxer/<meeting-uuid>/message.txt`.
+
+### 4. Post to Basecamp
+
+Use `create_message(project_id, subject, content)`:
+
+- **Subject**: `Fyxer: YYYY-MM-DD`
+- **Content**: contents of `message.txt`
+
+Capture the **message_id** from the response.
+
+### 5. Update Fyxer Index
+
+After a successful post, update the Fyxer Index document:
+
+1. If no Fyxer Index document exists, create one: `create_document(project_id, "Fyxer Index", "")`
+2. Read current content: `get_document(project_id, document_id)`
+3. Prepend a new line (newest first): `<meeting-uuid> | <date> | <message-id> | <subject>`
+4. Update: `update_document(project_id, document_id, title="Fyxer Index", content=updated_content)`
+
+If the index update fails after a successful post, warn the user. The message is posted but the index is stale. Run reconciliation later (see `basecamp-index.md`).
+
+## Format Rules
+
+- **Plain text only** — Basecamp prefers plain text over HTML
+- **YAML frontmatter** — machine-parseable so other Claude Code instances can search and parse meeting context
+- **Transcript only in body** — summary and action items belong on relevant Basecamp todos, not in this message
+- **Consistent title** — `Fyxer: YYYY-MM-DD` keeps messages uniform and sortable
+
+## Finding Posted Transcripts
+
+Check the index: `list_documents(project_id)` → find `Fyxer Index` → `get_document`
+View a specific transcript: `get_message(project_id, message_id)` using the message_id from the index
+Browse all messages: `list_messages(project_id)` — Fyxer posts use the title format `Fyxer: YYYY-MM-DD`
+
+## Dependencies
+
+- Basecamp MCP (`create_message`, `create_document`, `update_document`, `list_documents`, `get_document` tools) — see `simpleapps:workflow` skill (`basecamp.md`) for full MCP tool reference

package/skills/simpleapps/github/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: github
+description: GitHub conventions for SimpleApps. Covers org structure, local project layout, wiki-as-docs workflow, issue creation, PR workflows, and gh CLI usage. Use when creating issues, PRs, setting up repos, or working with GitHub wikis.
+---
+
+# GitHub
+
+## Organization
+
+All SimpleApps repos live under the **`simpleapps-com`** GitHub org.
+
+Repository pattern: `simpleapps-com/<repo-name>`
+
+## Authentication
+
+Use the `gh` CLI for all GitHub operations:
+
+```bash
+gh auth status          # Check auth status
+gh auth setup-git       # Configure gh as git credential helper
+```
+
+If `git push` fails with 401/403, run `gh auth setup-git` to fix credentials.
+
+## Key Topics
+
+- **Wiki as context** — See `wiki-as-context.md` for why the wiki is the source of truth and how to write for both humans and AI agents.
+- **Project structure** — See `project-structure.md` for the `{project}/[repo|wiki]` layout, what goes where, and wiki conventions.
+- **Issues & pull requests** — See `issues-prs.md` for issue templates, PR commands, and cross-linking with Basecamp.
+
+## Quick Reference
+
+```bash
+# Pushing
+gh auth setup-git && git push origin <branch>
+git push origin <tag>
+
+# Issues
+gh issue create --repo simpleapps-com/<repo> --title "type: desc" --body "..."
+gh issue list --repo simpleapps-com/<repo>
+
+# PRs
+gh pr create --repo simpleapps-com/<repo> --title "title" --body "..."
+gh pr list --repo simpleapps-com/<repo>
+```

package/skills/simpleapps/github/issues-prs.md

@@ -0,0 +1,89 @@
+# Issues & Pull Requests
+
+## Issues
+
+### Creating Issues
+
+MUST always use `--repo simpleapps-com/<repo>` to target the correct org. MUST ask the user which repo to create the issue in — never assume.
+
+### Issue Title
+
+- Use conventional commit style: `fix: description`, `feat: description`, `chore: description`
+- SHOULD be a technical description, not the client's words
+- Keep under 70 characters
+
+### Issue Body
+
+Every issue MUST include these sections:
+
+```markdown
+## Problem
+What is broken, missing, or needed? Include error messages, URLs, or screenshots if relevant.
+
+## Expected Behavior
+What SHOULD happen instead? Be specific.
+
+## Acceptance Criteria
+- [ ] Concrete, testable criteria
+- [ ] Each item is independently verifiable
+
+## Context
+Any additional info: related issues, affected files, workarounds, reproduction steps.
+```
+
+For bug reports, also include:
+- **Steps to Reproduce** — numbered steps to trigger the bug
+- **Current Behavior** — what actually happens (with error messages)
+
+### Labels
+
+Use labels to categorize: `bug`, `feature`, `enhancement`
+
+### Example
+
+```bash
+gh issue create --repo simpleapps-com/<repo> \
+  --title "fix: search endpoint returns 404" \
+  --body "$(cat <<'ISSUE'
+## Problem
+The `search` MCP tool returns HTTP 404 on every query. This prevents finding content across projects.
+
+## Expected Behavior
+Search SHOULD return matching results, consistent with the Basecamp web UI.
+
+## Acceptance Criteria
+- [ ] Search returns results for known content
+- [ ] Error handling for empty results
+
+## Context
+BCX API may not expose a search endpoint. Web UI search at `/search?q=...` works.
+ISSUE
+)"
+```
+
+### Managing Issues
+
+```bash
+gh issue list --repo simpleapps-com/<repo>                    # List open issues
+gh issue list --repo simpleapps-com/<repo> --state all        # Include closed
+gh issue view <number> --repo simpleapps-com/<repo>           # View issue details
+gh issue close <number> --repo simpleapps-com/<repo>          # Close issue
+gh issue close <number> --repo simpleapps-com/<repo> --comment "message"  # Close with comment
+```
+
+### Closing via Commit
+
+Include `Closes #N` in the commit message body to auto-close issues when pushed.
+
+## Pull Requests
+
+```bash
+gh pr create --repo simpleapps-com/<repo> --title "title" --body "description"
+gh pr list --repo simpleapps-com/<repo>
+gh pr view <number> --repo simpleapps-com/<repo>
+gh pr merge <number> --repo simpleapps-com/<repo>
+```
+
+## Cross-Linking with Basecamp
+
+When working on client tasks that originate in Basecamp, see the `simpleapps:workflow` skill for the full Basecamp-to-GitHub cross-linking process.

package/skills/simpleapps/github/project-structure.md

@@ -0,0 +1,102 @@
+# Project Structure & Wiki Workflow
+
+## Local Layout
+
+Every project MUST use this layout:
+
+```
+{project}/
+├── repo/    # Main git repo (simpleapps-com/<name>.git)
+└── wiki/    # GitHub wiki repo (simpleapps-com/<name>.wiki.git)
+```
+
+The parent `{project}/` directory is NOT a git repo — it's a local wrapper that keeps the code repo and wiki side-by-side.
+
+## Why This Pattern
+
+- GitHub wikis are separate git repos. Cloning them alongside the code keeps everything local and searchable.
+- AI agents (Claude Code) can `Read` wiki files from disk instantly instead of fetching URLs.
+- The wiki becomes the **source of truth for dev docs**. The repo stays focused on product code.
+
+## Setting Up a New Project
+
+```bash
+mkdir {project}
+cd {project}
+git clone https://github.com/simpleapps-com/<name>.git repo
+git clone https://github.com/simpleapps-com/<name>.wiki.git wiki
+```
+
+If the wiki repo doesn't exist yet, create it by adding any page via the GitHub wiki UI first, then clone.
+
+## What Goes Where
+
+| Content | Location | Examples |
+|---------|----------|---------|
+| Product code | `repo/` | Source, tests, configs, SKILL.md files |
+| Dev documentation | `wiki/` | Architecture, guides, specs, conventions |
+| Repo README | `repo/README.md` | Minimal — quick start + link to wiki |
+| Repo `.claude/rules/` | `repo/` | Minimal summaries referencing wiki pages |
+| Repo `.claude/CLAUDE.md` | `repo/` | Quick reference + wiki links |
+
+Rule of thumb: if a `.md` file isn't built into the end product, it belongs in the wiki.
+
+## Referencing Wiki from Repo
+
+Repo files SHOULD use **relative filesystem paths** to reference wiki content:
+
+```markdown
+Full docs: ../../../wiki/Versioning.md
+```
+
+Relative paths work for Claude Code (local file reads). GitHub URLs require network access and are slower.
+
+## Wiki Conventions
+
+### Page Naming
+
+- Use **PascalCase** with hyphens: `Getting-Started.md`, `Plugin-Structure.md`
+- Match the pattern used in GitHub wiki URLs: `wiki/Page-Name`
+
+### _Sidebar.md
+
+Every wiki MUST have a `_Sidebar.md` for navigation. Group pages by topic:
+
+```markdown
+**[[Home]]**
+
+**Getting Started**
+- [[Getting-Started]]
+
+**Architecture**
+- [[Architecture]]
+- [[Plugin-Structure]]
+
+**Development**
+- [[Development]]
+- [[Versioning]]
+```
+
+### Linking
+
+- Use `[[Page-Name]]` wiki links for internal links (renders on GitHub wiki)
+- Use `[[Display Text|Page-Name]]` for custom link text
+
+### Content Guidelines
+
+- Wiki pages are the **full, detailed** version of documentation
+- Each page SHOULD be self-contained — don't assume the reader has seen other pages
+- Include examples, code blocks, and tables where they help
+- Use RFC 2119 keywords (MUST/SHOULD/MAY) for requirements
+
+### Committing Wiki Changes
+
+The wiki is a regular git repo. Commit and push like any other:
+
+```bash
+cd {project}/wiki
+git add -A && git commit -m "docs: add architecture page"
+git push origin master
+```
+
+Note: GitHub wikis typically use `master` as the default branch, not `main`.

package/skills/simpleapps/github/wiki-as-context.md

@@ -0,0 +1,162 @@
+# Wiki as Context
+
+The GitHub wiki is the **single source of truth** for how a project works. It is not an afterthought or a place to dump notes — it is the primary context that drives development.
+
+## The Problem
+
+Documentation scattered across a codebase creates friction:
+
+- `.claude/rules/` files, README.md, inline comments, and docs/ folders all compete as sources of truth
+- AI agents waste tokens reading large files to find relevant context
+- New team members don't know where to look
+- Docs rot because they live next to code and get forgotten
+
+## The Solution
+
+The wiki is the **spec**. The repo is the **implementation**.
+
+| Wiki | Repo |
+|------|------|
+| Architecture decisions | Code that implements them |
+| API specs | API code |
+| Conventions and standards | Code that follows them |
+| Onboarding guides | Nothing — wiki is self-contained |
+| Release processes | Automation scripts |
+| Full explanations | Minimal pointers back to wiki |
+
+## How It Works
+
+### 1. Wiki First
+
+When starting new work, check the wiki first. If the wiki doesn't cover it, write the wiki page before writing code. The wiki defines *what* and *why*. The code implements *how*.
+
+### 2. Repo References Wiki
+
+Repo files (`.claude/CLAUDE.md`, `.claude/rules/`, `README.md`) SHOULD be **minimal** — just enough to orient, then point to the wiki for details.
+
+```markdown
+# Versioning
+
+Full docs: ../../../wiki/Versioning.md
+
+`VERSION` file = source of truth. All version fields MUST match.
+```
+
+### 3. AI Agents Read Wiki Locally
+
+Because the wiki is cloned alongside the repo (see `project-structure.md`), AI agents read wiki pages as local files. No network requests, no URL fetching — just `Read ../../../wiki/Architecture.md`.
+
+This means wiki pages are both human documentation AND machine context.
+
+### 4. Wiki Evolves with the Project
+
+The wiki is not write-once. As the codebase changes:
+
+- Update affected wiki pages in the same work session
+- Add new pages when new patterns emerge
+- Remove pages when features are deprecated
+- Keep the `_Sidebar.md` current
+
+## Three Audiences
+
+Every wiki page serves three audiences simultaneously:
+
+| Audience | What they need | How they read |
+|----------|---------------|---------------|
+| **Junior devs** | Explanations of *why*, step-by-step instructions, examples they can copy | Top to bottom, following links for context |
+| **Senior devs** | Quick reference, architecture decisions, conventions to follow | Scan for the section they need, skip the rest |
+| **AI agents** | Unambiguous specs, exact commands, clear requirements (MUST/SHOULD/MAY) | Load the full wiki into context, act on it |
+
+### Writing for All Three
+
+- **Lead with a summary** — seniors and agents get what they need fast, juniors get orientation
+- **Explain the *why* before the *how*** — juniors learn the reasoning, seniors confirm their assumptions, agents get decision context
+- **Use tables for reference data** — scannable for seniors, parseable for agents, structured for juniors
+- **Use code blocks for anything copy-pasteable** — all three audiences benefit from exact commands
+- **Use RFC 2119 keywords (MUST/SHOULD/MAY)** — removes ambiguity for everyone, especially agents
+- **Include examples** — juniors learn by example, agents use them as patterns
+
+### Keep Pages Self-Contained
+
+Each page SHOULD make sense on its own. A junior dev landing on any page SHOULD be able to understand it without reading the rest of the wiki.
+
+### Follow the Writing Style Skill
+
+All wiki content MUST follow the `simpleapps:writing-style` skill:
+
+- **RFC 2119 keywords** — MUST/SHOULD/MAY in ALL CAPS for requirements, lowercase for casual suggestions
+- **Token efficiency** — action verbs first, no filler, specific over generic, Bottom Line Up Front
+- **Developer-facing tone** — technical and concise, include file references and acceptance criteria
+- **Expand for onboarding and architecture** — juniors and future devs need the "why"
+- **Cut everywhere else** — two sentences that answer the question beat two pages that fill the context window
+
+The wiki is developer-facing documentation. It is NOT client-facing. Write for devs and AI agents, not for non-technical readers.
+
+### Link with Anchor Precision
+
+When referencing other wiki pages, MUST link directly to the relevant section using `#` anchors — not just the page.
+
+```markdown
+# Good — links to exact section
+See [[Versioning#version-bump-procedure]] for the step-by-step process.
+Check [[Architecture#three-layers]] for how marketplace, plugins, and CLI relate.
+
+# Bad — links to top of page, reader has to hunt
+See [[Versioning]] for details.
+Check [[Architecture]] for more info.
+```
+
+This matters for two reasons:
+- **Devs** jump straight to the answer instead of scrolling through a page
+- **AI agents** use anchor links as an attention signal — a `#section` reference tells the agent exactly which part of a page is relevant to the current task, reducing noise in a 20K token wiki
+
+### The 20K Token Budget
+
+The entire wiki MUST stay under **20K tokens** (~60KB of markdown). This is a hard constraint, not a guideline.
+
+Why 20K: with a 200K token context window, the full wiki never exceeds 10% of available context. This means an AI agent can load the **entire wiki** into active context at the start of a session and keep it there throughout. No selective loading, no missed context, no stale references — the agent always has the complete picture.
+
+If the wiki approaches the budget:
+- Tighten language — cut filler, use tables over prose
+- Merge overlapping pages
+- Move implementation details back to code comments where they belong
+- Archive obsolete pages (delete, don't hoard)
+
+To check the current budget:
+```bash
+wc -c {project}/wiki/*.md
+```
+
+Rough conversion: 1 token ≈ 3 bytes of markdown. So 20K tokens ≈ 60KB.
+
+### Right-Size Each Page
+
+- Too short = missing context, agent has to search elsewhere
+- Too long = wasted tokens, buried signal
+- Target: enough to act on without reading anything else
+
+## The Feedback Loop
+
+```
+Wiki defines → Code implements → Learnings update wiki → Repeat
+```
+
+When code reveals that the wiki is wrong or incomplete, update the wiki immediately. The wiki MUST reflect reality, not aspirations.
+
+## When to Update the Wiki
+
+- **New feature** — Write the wiki page first (spec), then implement
+- **Bug fix** — If the fix reveals a gap in documentation, update the wiki
+- **Architecture change** — Update Architecture page before or during the change
+- **New convention** — Add to the relevant wiki page so the team adopts it
+- **Onboarding friction** — If someone asks "where is X?", the answer should be a wiki link. If it's not, create the page.
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Write long README.md files in the repo | Minimal README + wiki link |
+| Duplicate wiki content in `.claude/rules/` | Thin rules that reference wiki |
+| Leave wiki pages stale after code changes | Update wiki in the same session |
+| Use the wiki as a dumping ground for notes | Structure pages with clear purpose |
+| Write wiki pages only humans can understand | Write for both humans and AI agents |

package/skills/simpleapps/work-habits/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: work-habits
+description: How to work autonomously on extended tasks. Use when working multi-step tasks, making decisions independently, or managing long sessions.
+---
+
+# Work Habits
+
+## Do exactly what was asked
+
+Do not add features, refactor surrounding code, or "improve" beyond the request. One task asked = one task delivered. Ask before expanding scope.
+
+## Use the right tool
+
+Prefer dedicated tools over Bash equivalents — they are faster, need no permissions, and produce cleaner output:
+- Read not `cat`/`head`/`tail`
+- Grep not `grep`/`rg`
+- Glob not `find`/`ls`
+- Edit not `sed`/`awk`
+
+Reserve Bash for commands that have no dedicated tool equivalent.
+
+## Protect the context window
+
+- Prefer targeted searches over broad exploration
+- Use subagents for verbose operations (test runs, log analysis, large file reads)
+- `/clear` between unrelated tasks
+- Two sentences that answer the question beat two pages that fill the context window
+
+## Verify your own work
+
+Run tests, check output, compare results. YOU MUST NOT mark work complete without verification. If you can't verify, say so.
+
+## Track progress
+
+Use TodoRead/TodoWrite on multi-step tasks. Mark items in-progress before starting, completed after verifying.
+
+## Know when to stop and ask
+
+**Ask** when: requirements are ambiguous, multiple valid approaches exist, an action is destructive or irreversible, you've failed the same approach twice.
+
+**Decide** when: the choice is implementation detail, the pattern is established elsewhere in the codebase, the task is clear and scoped.
+
+## Recover from mistakes
+
+Wrong approach? Stop, revert, try differently. Do not keep layering fixes on a broken foundation. Two failed attempts at the same approach = change strategy.

package/skills/simpleapps/workflow/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: workflow
+description: How we track and deliver work. Covers the Basecamp-to-GitHub flow for client requests, task tracking, and cross-linking. Use when working on client tasks, creating issues, or checking assignments.
+---
+
+# Workflow
+
+## How Work Flows
+
+1. **Client request** arrives in Basecamp (todo, message, or comment)
+2. **Read and summarize** the Basecamp todo to understand the request
+3. **Create a GitHub issue** with technical details for implementation
+4. **Cross-link** — Basecamp todo URL in the GitHub issue body, GitHub issue URL in Basecamp todo comments
+5. **Do the work** in code, referencing the GitHub issue
+6. **Report back** through Basecamp for the client; keep implementation details in GitHub
+
+## Tool Boundaries
+
+| Tool | Audience | Purpose |
+|------|----------|---------|
+| **Basecamp** | Client-facing | Task requests, status updates, client communication |
+| **GitHub Issues** | Developer-facing | Technical details, implementation, internal findings |
+
+Basecamp todos and GitHub issues SHOULD cross-link (many-to-many — one todo MAY relate to multiple issues and vice versa).
+
+**Note**: GitHub access is granted on request. If the user does not have repo access, skip steps 3-5 above and use Basecamp only. Do not assume access — check with `gh` or ask the user.
+
+## Tooling
+
+The `basecamp` MCP server (bundled with this plugin) provides direct API access to Basecamp 2. Use MCP tools (`get_todo`, `list_my_todos`, `list_documents`, etc.) as the primary method. Chrome browser automation is the fallback if MCP is unavailable.
+
+**First-time setup**: User MUST run `uv run basecamp-auth` once to authorize. Credentials are saved to `~/.simpleapps/basecamp.json`.
+
+## References
+
+- See `basecamp.md` for MCP tools, Chrome fallback, and Basecamp navigation
+- See `github.md` for Basecamp-to-GitHub cross-linking
+- See `simpleapps:github` skill for GitHub org conventions and `gh` CLI usage
+- See `simpleapps:fyxer` skill for Fyxer meeting transcript processing and Basecamp posting

package/skills/simpleapps/workflow/basecamp.md

@@ -0,0 +1,199 @@
+# Basecamp 2 Reference
+
+IMPORTANT: YOU MUST NOT create, edit, or delete anything in Basecamp without user permission.
+
+**Content format**: All write tools SHOULD use plain text with line breaks, NOT HTML. Basecamp returns HTML in responses but prefers plain text for creation.
+
+## Setup
+
+Credentials stored at `~/.simpleapps/basecamp.json`. If missing, ask the user to run:
+
+```bash
+uv run basecamp-auth
+```
+
+This opens the browser for OAuth, user clicks "Allow", credentials are saved automatically.
+
+## MCP Tools (Preferred)
+
+The `basecamp` MCP server is bundled with this plugin and starts automatically. API reference: https://github.com/basecamp/bcx-api
+
+### Projects
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List projects. status: 'active', 'drafts', or 'archived' |
+| `get_project` | Get project details by project_id |
+| `create_project` | Create a new project (name, description) |
+| `update_project` | Update project name/description |
+| `archive_project` | Archive or unarchive a project (archive=False to reactivate) |
+| `delete_project` | Delete a project permanently |
+
+### People
+| Tool | Description |
+|------|-------------|
+| `list_people` | List all people on the account |
+| `get_person` | Get person details by person_id |
+| `get_me` | Get the authenticated user's profile |
+| `list_person_projects` | List projects accessible to a person |
+| `delete_person` | Remove a person from the account (admin only) |
+
+### Todos
+| Tool | Description |
+|------|-------------|
+| `get_todo` | Get a single todo with comments and attachments (project_id, todo_id) |
+| `list_todos` | List todos in a project. status: 'remaining', 'completed', or 'all' |
+| `list_todos_due_since` | List todos due after a date (YYYY-MM-DD) |
+| `list_my_todos` | List all open todos assigned to the current user (paginated) |
+| `list_assigned_todos` | List open todos assigned to any person_id |
+| `create_todo` | Create a todo in a todo list (project_id, todolist_id, content, assignee_id, due_date) |
+| `update_todo` | Update a todo's content, due date, or assignee |
+| `assign_todo` | Reassign a todo to a different person_id |
+| `close_todo` | Mark a todo as completed/closed |
+| `reopen_todo` | Reopen a completed todo |
+| `delete_todo` | Delete a todo permanently |
+
+### Comments
+| Tool | Description |
+|------|-------------|
+| `create_comment` | Add a comment to a todo (plain text) |
+| `delete_comment` | Delete a comment permanently |
+
+### Todo Lists
+| Tool | Description |
+|------|-------------|
+| `list_todolists` | List active todo lists in a project |
+| `list_all_todolists` | List todo lists across all projects. status: 'active', 'completed', or 'trashed' |
+| `get_todolist` | Get all todos in a specific todo list |
+| `create_todolist` | Create a new todo list (project_id, name, description) |
+| `update_todolist` | Update a todo list's name, description, or position |
+| `delete_todolist` | Delete a todo list permanently |
+
+### Messages
+| Tool | Description |
+|------|-------------|
+| `list_messages` | List messages/discussions in a project (via topics) |
+| `get_message` | Get a message with comments and attachments |
+| `create_message` | Create a new discussion (project_id, subject, content) |
+| `update_message` | Update a message's subject/content |
+| `delete_message` | Delete a message permanently |
+
+Note: Messages may not be available on all Basecamp plans.
+
+### Documents
+| Tool | Description |
+|------|-------------|
+| `list_documents` | List documents. project_id=0 for all projects |
+| `get_document` | Get a single document (e.g., site-info) |
+| `create_document` | Create a new document (title, content) |
+| `update_document` | Update a document's title/content |
+| `delete_document` | Delete a document permanently |
+
+### Calendar Events
+| Tool | Description |
+|------|-------------|
+| `list_calendars` | List all calendars |
+| `list_calendar_events` | List events. Filter by project_id, start_date, end_date, past |
+| `get_calendar_event` | Get a specific calendar event |
+| `create_calendar_event` | Create an event (summary, starts_at, description, all_day, ends_at, remind_at) |
+| `update_calendar_event` | Update an event's fields |
+| `delete_calendar_event` | Delete a calendar event |
+
+### Topics
+| Tool | Description |
+|------|-------------|
+| `list_topics` | List topics. project_id=0 for all. archived=True for archived |
+| `archive_topic` | Archive a topic |
+| `activate_topic` | Reactivate an archived topic |
+
+### Attachments & Uploads
+| Tool | Description |
+|------|-------------|
+| `list_attachments` | List attachments. project_id=0 for all (paginated) |
+| `get_attachment` | Get attachment metadata and download URL (project_id, attachment_id) |
+| `download_attachment` | Download attachment to local file (project_id, attachment_id) |
+| `get_upload` | Get an upload with comments |
+| `create_upload` | Upload a local file to a project's Files section |
+| `delete_upload` | Delete an upload (move to trash) |
+
+### Activity
+| Tool | Description |
+|------|-------------|
+| `list_events` | Activity log since a datetime. Filter by project_id or person_id |
+
+### Access Management
+| Tool | Description |
+|------|-------------|
+| `list_accesses` | List people with access to a project |
+| `grant_access` | Grant team access (comma-separated ids and/or email_addresses) |
+| `grant_client_access` | Grant client-level access (comma-separated ids and/or email_addresses) |
+| `revoke_access` | Revoke a person's project access |
+
+### Stars
+| Tool | Description |
+|------|-------------|
+| `list_stars` | List starred/favorite projects |
+| `star_project` | Star (bookmark) a project |
+| `unstar_project` | Remove star from a project |
+
+### Forwards
+| Tool | Description |
+|------|-------------|
+| `list_forwards` | List email forwards. project_id=0 for all |
+| `get_forward` | Get a specific email forward with comments |
+
+**Note**: The BCX API does not have a search endpoint. To find content, use `list_topics(project_id)` to browse, or `list_messages(project_id)` for messages. For cross-project browsing, use `list_topics()` (no project_id) to get recent topics across all projects.
+
+**Extracting IDs from Basecamp URLs**: A URL like `https://basecamp.com/2805226/projects/18932786/todos/514631271` gives you project_id=`18932786` and todo_id=`514631271`.
+
+## Downloading Attachments
+
+Attachments can be on todos, comments, messages, or uploads. To retrieve them:
+
+1. **Discover**: Call `get_todo` or `get_message` — attachments appear with IDs in both the top-level section and within individual comments
+2. **Inspect** (optional): Call `get_attachment(project_id, attachment_id)` to see metadata, size, content type, and download URL
+3. **Download**: Call `download_attachment(project_id, attachment_id)` — saves to `~/.simpleapps/downloads/{project_id}/`
+4. **Read**: Use the `Read` tool on the local file path to view content (works for images, PDFs, Excel, text)
+
+To browse all attachments in a project, use `list_attachments(project_id)`.
+
+## Chrome Fallback
+
+If the MCP server is unavailable (credentials expired, server not running), use Chrome:
+
+1. Use `tabs_context_mcp` to get current tabs
+2. Create a new tab or use an existing Basecamp tab
+3. Navigate to the Basecamp page
+4. Use `get_page_text` to extract content
+
+**Base URL**: `https://basecamp.com/2805226`
+
+**Top nav**: Projects | Calendar | Everything | Progress | Everyone | **Me**
+
+| Page | Path |
+|------|------|
+| Dashboard | `/` |
+| All projects | `/projects` |
+| My assignments | click "Me" in top nav |
+| Project overview | `/projects/<project_id>` |
+| Todo lists | `/projects/<project_id>/todolists` |
+| Documents | `/projects/<project_id>/documents` |
+
+**Me** page (`/people/<person_id>`) — open to-dos (~45+ shows a "See all X open to-dos" link, YOU MUST click it). The full list is at `/people/<person_id>/outstanding_todos`.
+
+**JSON API via Chrome**: Navigate to `/api/v1/projects/<project_id>/todos/<todo_id>.json` then use `get_page_text`. WebFetch will NOT work — Chrome carries session cookies.
+
+## Fyxer Meeting Transcripts
+
+To post Fyxer meeting recordings as Basecamp Discussions, see the `simpleapps:fyxer` skill. It handles extraction, local caching, duplicate detection, and posting via `create_message`.
+
+## Site Info Documents
+
+Each Basecamp project SHOULD have a **site-info** text document in its Documents section. It contains site-specific details like siteId and domain name needed for GitHub issues and development work. Use `list_documents` + `get_document` to find it. If no site-info document exists, ask the user to create one.
+
+## Tips
+
+- Cache the user's `person_id` on first visit for the session
+- Start from `list_my_todos` for "what do I need to work on?"
+- Use `list_people` to find person_id before calling `assign_todo`
+- If you get a 401 or auth error, ask the user to re-run `basecamp-auth`
+- If an endpoint returns 404, the feature may not be available on this Basecamp plan

package/skills/simpleapps/workflow/github.md

@@ -0,0 +1,34 @@
+# Basecamp → GitHub Cross-Linking
+
+When a client request in Basecamp needs development work, create a GitHub issue and cross-link them.
+
+## Creating Issues from Basecamp Todos
+
+Before creating an issue, gather context from Basecamp (see `basecamp.md` for full MCP tool reference):
+1. Use `get_todo` to read the Basecamp todo and summarize the client request
+2. Use `list_documents` + `get_document` to find the project's **site-info** document for siteId and domain name. If no site-info document exists, ask the user to create one in Basecamp.
+
+See the `simpleapps:github` skill for `gh` CLI usage and org conventions.
+
+Issue template for Basecamp-linked issues:
+
+```bash
+gh issue create --repo simpleapps-com/<repo> \
+  --title "<brief technical title>" \
+  --body "## Basecamp
+<basecamp_todo_url>
+
+## Client
+<client/project name> — <domain> (siteId: <siteId>)
+
+## Summary
+<technical summary of what needs to be done>
+
+## Acceptance Criteria
+- [ ] <criteria from the Basecamp request>"
+```
+
+## Cross-Linking
+
+- Include the Basecamp todo URL in the GitHub issue body (under a `## Basecamp` heading)
+- After creating the issue, provide the GitHub issue URL to the user so they can add it to the Basecamp todo comments

package/skills/simpleapps/writing-style/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: writing-style
+description: Writing standards for code comments, documentation, specs, PRDs, and team communication. Applies RFC 2119 requirement language and token-efficient writing.
+---
+
+# Writing Style
+
+Apply these standards to all written output: code comments, docs, specs, PRDs, wiki pages, commit messages, and team communication.
+
+## RFC 2119 Requirement Language
+
+Spec: https://www.rfc-editor.org/rfc/rfc2119
+
+Use ALL CAPS when invoking requirement levels:
+
+- **MUST / REQUIRED / SHALL** — absolute requirement, no exceptions
+- **MUST NOT / SHALL NOT** — absolute prohibition
+- **SHOULD / RECOMMENDED** — strong recommendation, exceptions need justification
+- **SHOULD NOT / NOT RECOMMENDED** — discouraged, acceptable with careful reasoning
+- **MAY / OPTIONAL** — truly optional, implementer's choice
+
+Use lowercase for casual suggestions: "you should consider..." vs "you SHOULD implement..."
+
+Decision framework: Does the system break without it? → MUST. Degrades? → SHOULD. No impact? → MAY.
+
+In CLAUDE.md and skill instructions, use "YOU MUST" or "IMPORTANT" as emphasis markers to improve adherence to critical rules.
+
+## Token Efficiency
+
+Every token costs time, money, and cognitive load. Be concise without losing clarity.
+
+**Rules:**
+1. Start with action verbs: fix, add, update, remove
+2. Use file:line references: `auth.ts:45` not "authentication file line 45"
+3. Eliminate filler: actually, basically, in order to, it's worth noting
+4. Choose specific over generic: "Redis cache" not "caching solution"
+5. Bottom Line Up Front — lead with the answer, then context
+
+**By audience:**
+- **Client-facing (Basecamp)**: Plain language, no jargon, explain impact not implementation. The reader is non-technical — write for clarity over brevity.
+- **Developer-facing (GitHub issues, PRs, wiki)**: Technical and concise. Convey context for developers and AI agents — include file references, reproduction steps, and acceptance criteria.
+- **Internal (code comments, commits)**: Minimal. Reader has full codebase context.
+
+**By format:**
+- **PRDs**: Bullet points, not paragraphs
+- **Specs**: Lead with requirements (MUST/SHOULD/MAY)
+- **Tasks**: Action verb + target
+- **Code comments**: Only where logic isn't self-evident
+- **Reviews**: What changed, not why
+
+**When to expand:**
+- User stories, onboarding docs, error messages — reader has no prior context
+- Architecture decisions — future developers need the "why"
+- External-facing docs — audience can't ask follow-up questions
+
+**When to cut:**
+- Internal specs, tasks, code comments — reader has shared context
+- Commit messages, PR titles — scanning speed matters
+- Anything repeating what the code already says
+
+Default to brief. Expand only when the reader cannot infer meaning from context. Two sentences that answer the question beat two pages that fill the context window.
+
+## Claude Code Keywords
+
+Thinking trigger words (`think`, `think hard`, `ultrathink`) are deprecated. Extended thinking is on by default. Use `/effort` (low/medium/high/max) for control.