@simpleapps-com/augur-skills 0.0.1 → 0.0.2

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.2",
   "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/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,37 @@
+---
+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 GitHub issue creation and cross-linking

package/skills/simpleapps/workflow/basecamp.md

@@ -0,0 +1,125 @@
+# Basecamp 2 Reference
+
+IMPORTANT: YOU MUST NOT create, edit, or delete anything in Basecamp — except reassigning todos via `assign_todo`.
+
+## 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 |
+
+### 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 |
+
+### Todos
+| Tool | Description |
+|------|-------------|
+| `get_todo` | Get a single todo with comments (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 |
+| `assign_todo` | Reassign a todo to a different person_id |
+
+### 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 |
+
+### Messages
+| Tool | Description |
+|------|-------------|
+| `list_messages` | List messages in a project |
+| `get_message` | Get a message with comments |
+
+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) |
+
+### 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 |
+
+### Topics, Events, Attachments
+| Tool | Description |
+|------|-------------|
+| `list_topics` | List topics. project_id=0 for all. archived=True for archived |
+| `list_events` | Activity log since a datetime. Filter by project_id or person_id |
+| `list_attachments` | List attachments. project_id=0 for all (paginated) |
+| `get_upload` | Get an upload with comments |
+
+### Other
+| Tool | Description |
+|------|-------------|
+| `list_accesses` | List people with access to a project |
+| `list_stars` | List starred/favorite projects |
+| `list_forwards` | List email forwards. project_id=0 for all |
+| `get_forward` | Get a specific email forward with comments |
+| `search` | Search 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`.
+
+## 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.
+
+## 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,46 @@
+# GitHub Issues Reference
+
+## Creating Issues from Basecamp Todos
+
+Before creating an issue, gather context:
+1. Use `get_todo` (MCP) to read the Basecamp todo and summarize the client request
+2. Use `list_documents` + `get_document` (MCP) 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.
+
+Use `gh issue create` to create issues linked to Basecamp todos:
+
+```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
+
+## Conventions
+
+- YOU MUST ALWAYS ask the user which GitHub repo to create the issue in — it could be the client site repo, the augur repo, or any other repo in the org
+- Issue title SHOULD be a technical description, not the client's words
+- Reference the Basecamp todo as the source of the request
+- Use labels to categorize (bug, feature, enhancement)
+- Assign to the appropriate developer
+
+## Useful Commands
+
+```bash
+gh issue list --repo simpleapps-com/<repo>           # List open issues
+gh issue view <number> --repo simpleapps-com/<repo>  # View issue details
+gh issue create --repo simpleapps-com/<repo>         # Create new issue
+```

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.