diff --git a/CHANGELOG.md b/CHANGELOG.md index e59095d..68d98ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ - Add `security-patterns` — PreToolUse on Edit/Write catches eval, XSS, shell injection, weak hashes, hardcoded secrets across JS/TS/Python/Go - Add `audit-trail` — logs all Bash commands to `.devkit/audit.log` with UTC timestamps, auto-rotates at 10k lines - Add `slop-detect` — PostToolUse on Edit/Write catches excessive docs, restating comments, JSDoc overuse +- Add `pr-gate` — prompts to run pr-ready pipeline before `gh pr create`, 10-minute cooldown ### Upgraded - Upgrade `self:perf` to hypothesis-driven investigation — evidence gathering, ranked hypotheses, one-at-a-time testing with 3x benchmark runs @@ -21,9 +22,12 @@ - Fix superpowers install: use `@claude-plugins-official`, not separate marketplace ### Skills +- Convert 6 commands to context-activated skills (no slash command needed): test-gen, doc-gen, changelog, onboard, research, scrape +- Add `dont-reinvent` skill — prefer existing solutions over custom code, reduce maintenance burden +- Add `gcli` skill — Google Workspace CLI reference with safety confirmation gate - Remove 5 skills that overlap with superpowers: brainstorming, planning, writing-tests, skill-authoring, verify -- Keep 6 unique skills: executing, clean-code, dry, yagni, creating-workflows, stuck - Evaluated `code-simplifier` as replacement — rejected (thin, React-specific, no test verification) +- Commands reduced from 26 to 20, skills increased from 6 to 14 ### Fixes - Fix stop-gate: disabled — fires every turn, not just session end. Needs architectural redesign. diff --git a/README.md b/README.md index d691308..1342929 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,22 @@ Devkit focuses on enforcement, orchestration, and multi-agent workflows. For a c | **[commit-commands](https://github.com/anthropics/claude-plugins-official)** | Quick commits — auto-message `/commit`, one-shot `/commit-push-pr`, stale branch cleanup `/clean_gone` | `/plugin install commit-commands@claude-plugins-official` | | **[hookify](https://github.com/anthropics/claude-plugins-official)** | Hook creation — markdown-based rules, hot reload, conversation analysis for auto-detection | `/plugin install hookify@claude-plugins-official` | | **[skill-creator](https://github.com/anthropics/claude-plugins-official)** | Skill development — eval/benchmark framework, blind A/B comparison, iterative improvement | `/plugin install skill-creator@claude-plugins-official` | -| **[context-mode](https://github.com/mksglu/context-mode)** | Context window management — sandboxes large outputs, session continuity via SQLite, 98% savings | See repo for MCP server install | +| **[context-mode](https://github.com/mksglu/context-mode)** | Context window management — sandboxes large outputs, session continuity via SQLite, 98% savings | See below | + +#### Context Mode Install + +Plugin install (recommended — includes hooks + slash commands): +```bash +/plugin marketplace add mksglu/context-mode +/plugin install context-mode@context-mode +``` + +MCP-only install (lighter — sandbox tools only, no auto-routing): +```bash +claude mcp add context-mode -- npx -y context-mode +``` + +Verify with `/context-mode:ctx-doctor` (plugin install) or check MCP tools are available (MCP install). **Why these and not others?** We evaluated every plugin in the official marketplace. These are the ones that add unique value without duplicating what devkit already does. Notably: @@ -48,16 +63,18 @@ Devkit focuses on enforcement, orchestration, and multi-agent workflows. For a c │ers: │ feature │ pr-ready │ self-improve/test/ │ │ brain- │ bugfix │ pr-moni- │ lint/perf/migrate │ │ storm │ refactor │ tor │ │ -│ plan │ test-gen │ │ tri-review/debug/ │ -│ TDD │ decompose│ commit- │ security/test-gen │ -│ debug │ │ commands │ │ -│ │feature- │ │ pr-review-toolkit │ -│ │dev: │ │ │ -│ │ explore │ │ audit │ -│ │ design │ │ repo-map │ +│ plan │ decompose│ │ tri-review/debug/ │ +│ TDD │ │ commit- │ security/test-gen │ +│ debug │feature- │ commands │ │ +│ │dev: │ │ pr-review-toolkit │ +│ │ explore │ │ │ +│ │ design │ │ audit, repo-map │ ├──────────┴──────────┴──────────┴─────────────────────┤ +│ Auto skills: test-gen, doc-gen, changelog, onboard, │ +│ research, scrape (no slash command needed) │ +├──────────────────────────────────────────────────────┤ │ Always active: devkit hooks (safety, security, │ -│ audit trail, slop detection, post-validation) │ +│ audit trail, slop detection, pr-gate, post-validate) │ ├──────────────────────────────────────────────────────┤ │ Meta: hookify (create hooks), skill-creator (skills) │ │ context-mode (token management) │ @@ -72,18 +89,17 @@ Devkit focuses on enforcement, orchestration, and multi-agent workflows. For a c # Check what's available /devkit:status -# Generate tests for your code -/devkit:test-gen src/parser.ts +# These activate automatically — just ask naturally: +# "write tests for src/parser.ts" +# "generate a changelog" +# "help me understand this codebase" +# "research the best auth library for Node" +# "scrape this URL: https://example.com" -# Fix all lint errors automatically +# Slash commands for complex workflows: /self:lint --lint "npm run lint" --target src/ - -# Full PR preparation pipeline /devkit:pr-ready - -# Multi-agent code review (uses whatever CLIs you have) /tri:review - ``` --- @@ -94,20 +110,14 @@ Devkit focuses on enforcement, orchestration, and multi-agent workflows. For a c | Command | Description | |---|---| -| `/devkit:test-gen` | Generate test suite — writes tests, runs them, fixes failures | -| `/devkit:doc-gen` | Generate documentation from code analysis | | `/devkit:pr-ready` | Full PR pipeline — lint, test, security, changelog, create PR | | `/devkit:pr-monitor` | Post-PR review monitor — watches CI, resolves reviewer comments iteratively | | `/devkit:repo-map` | AST-based symbol index — exports, classes, imports, dependency graph, cached | -| `/devkit:onboard` | Generate codebase onboarding guide for new contributors | -| `/devkit:changelog` | Generate structured changelog from git history | | `/devkit:workflow` | Run user-defined YAML workflows from `workflows/` | | `/devkit:bugfix` | Full bug fix lifecycle — reproduce, diagnose, fix, regression test, verify | | `/devkit:feature` | Full feature lifecycle — brainstorm, plan, implement, test, lint, review | | `/devkit:refactor` | Full refactor lifecycle — analyze, plan, restructure, verify, compare | -| `/devkit:research` | Deep research — clarify, parallel search, analyze sources, synthesize | | `/devkit:decompose` | Goal decomposition — break into task DAG, assign agents, execute in dependency order | -| `/devkit:scrape` | URL-to-Markdown conversion via Jina Reader / Firecrawl / WebFetch | | `/devkit:audit` | Full project health audit — deps, vulnerabilities, licenses, lint, security | | `/devkit:status` | Health check — installed CLIs, available agents, ready commands | @@ -152,7 +162,24 @@ These run with whatever agents are available. Claude always runs. Codex and Gemi ## Skills -Coding methodology guides loaded as reference material when relevant commands run. +Skills activate automatically based on context — no slash command needed. Just ask naturally. + +### Context-Activated Workflows + +These replace slash commands. Ask naturally and the skill fires: + +| Skill | Triggers on | +|---|---| +| `devkit:test-gen` | "write tests for X", "add test coverage", "generate tests" | +| `devkit:doc-gen` | "document this module", "generate API docs", "write docs for" | +| `devkit:changelog` | "generate a changelog", "release notes", "what changed since" | +| `devkit:onboard` | "explain this codebase", "help me understand the architecture", "onboard" | +| `devkit:research` | "research X", "deep dive on", "compare approaches for" | +| `devkit:scrape` | "scrape this URL", "fetch content from", "extract from this page" | + +### Coding Principles + +Loaded as reference material when relevant: | Skill | Description | |---|---| @@ -160,16 +187,23 @@ Coding methodology guides loaded as reference material when relevant commands ru | `devkit:clean-code` | Meaningful names, small functions, single responsibility, flat nesting | | `devkit:dry` | Rule of Three, when duplication is fine, extracting the right abstraction | | `devkit:yagni` | Build only what's needed, no speculative features or premature abstractions | -| `devkit:creating-workflows` | How to create workflow YAML files — schema, step types, interpolation | +| `devkit:dont-reinvent` | Use existing libraries, tools, and stdlib before building custom solutions | | `devkit:stuck` | Detect agent looping/failing, structured recovery — backtrack, simplify, escalate | +### Tools + +| Skill | Description | +|---|---| +| `devkit:gcli` | Google Workspace CLI (Gmail, Calendar, Drive) via gcli with `--for-ai` | +| `devkit:creating-workflows` | How to create workflow YAML files — schema, step types, interpolation | + For brainstorming, planning, TDD, verification, and skill authoring — install [superpowers](https://github.com/obra/superpowers). --- ## Hooks -Devkit ships 7 hooks across 4 lifecycle events. All are installed automatically with the plugin — no setup required. +Devkit ships 8 hooks across 3 lifecycle events. All are installed automatically with the plugin — no setup required. ### PreToolUse @@ -178,6 +212,7 @@ Devkit ships 7 hooks across 4 lifecycle events. All are installed automatically | **safety-check** | Bash, Edit, Write | Blocks destructive commands (`rm -rf /`, `DROP TABLE`, private key writes). Prompts on risky operations (force push, `git reset --hard`, editing secrets). | | **security-patterns** | Edit, Write | Catches vulnerability patterns at creation time — `eval()`, XSS, shell injection, weak hashes, hardcoded secrets. Language-aware (JS/TS/Python/Go). | | **audit-trail** | Bash | Logs every command to `.devkit/audit.log` with UTC timestamps. Auto-rotates at 10k lines. | +| **pr-gate** | Bash | Detects `gh pr create` and prompts to run `/devkit:pr-ready` first. 10-minute cooldown. | | **rtk-rewrite** | Bash | Rewrites commands through [RTK](https://github.com/rtk-ai/rtk) for 60-90% token savings. No-op if RTK not installed. | ### PostToolUse @@ -253,24 +288,18 @@ devkit/ ├── manifest.json # Plugin manifest ├── ROADMAP.md # Implemented features and future plans ├── PREFERENCES.md # Agent behavior guidelines -├── commands/ # 26 commands +├── commands/ # 20 slash commands │ ├── tri-*.md # Multi-agent commands (5) │ ├── self-*.md # Self-improvement loops (5) │ ├── pr-ready.md # PR preparation pipeline │ ├── pr-monitor.md # Post-PR review monitor │ ├── repo-map.md # AST-based symbol index │ ├── audit.md # Project health audit -│ ├── test-gen.md # Test generation -│ ├── doc-gen.md # Documentation generation -│ ├── onboard.md # Codebase onboarding -│ ├── changelog.md # Changelog generation │ ├── workflow.md # YAML workflow runner │ ├── feature.md # Feature lifecycle │ ├── bugfix.md # Bug fix lifecycle │ ├── refactor.md # Refactor lifecycle -│ ├── research.md # Deep research │ ├── decompose.md # Goal decomposition -│ ├── scrape.md # URL-to-Markdown │ └── status.md # Health check ├── agents/ # 6 agents │ ├── reviewer.md # Opus, worktree isolation @@ -279,14 +308,22 @@ devkit/ │ ├── test-writer.md # Sonnet, worktree isolation │ ├── documenter.md # Haiku, worktree isolation │ └── security-auditor.md # Opus, worktree isolation -├── skills/ # 6 skills -│ ├── executing.md -│ ├── clean-code.md -│ ├── dry.md -│ ├── yagni.md -│ ├── creating-workflows.md -│ └── stuck.md -├── hooks/ # 7 hooks +├── skills/ # 14 skills (6 context-activated workflows + 8 principles/tools) +│ ├── test-gen.md # Auto: "write tests for X" +│ ├── doc-gen.md # Auto: "document this module" +│ ├── changelog.md # Auto: "generate a changelog" +│ ├── onboard.md # Auto: "explain this codebase" +│ ├── research.md # Auto: "research X" +│ ├── scrape.md # Auto: "scrape this URL" +│ ├── executing.md # Principle: methodical execution +│ ├── clean-code.md # Principle: readability +│ ├── dry.md # Principle: don't repeat yourself +│ ├── yagni.md # Principle: no speculative features +│ ├── dont-reinvent.md # Principle: use existing solutions +│ ├── stuck.md # Principle: loop recovery +│ ├── gcli.md # Tool: Google Workspace CLI +│ └── creating-workflows.md # Tool: YAML workflow authoring +├── hooks/ # 8 hooks │ ├── hooks.json # Hook config (auto-loaded) │ ├── safety-check.sh # Dangerous operation blocker │ ├── security-patterns.sh # Edit-time vulnerability detection @@ -294,6 +331,7 @@ devkit/ │ ├── rtk-rewrite.sh # Token optimization │ ├── post-validate.sh # Output validation │ ├── slop-detect.sh # AI pattern detection +│ ├── pr-gate.sh # PR pipeline prompt │ ├── subagent-stop.sh # Subagent work verification │ └── stop-gate.sh # Quality gate (disabled — needs redesign) ├── workflows/ # 12 YAML workflow definitions diff --git a/ROADMAP.md b/ROADMAP.md index d9b5d8f..ddbe270 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,10 +2,10 @@ ## Implemented -- **26 commands** — Solo workflows, self-improvement loops, multi-agent dispatch, project health audit, post-PR monitoring, AST repo mapping -- **6 skills** — Execution methodology, clean code principles (DRY, YAGNI), workflow authoring, stuck recovery +- **20 slash commands** — Lifecycle workflows, self-improvement loops, multi-agent dispatch, project health audit, post-PR monitoring, AST repo mapping +- **14 skills** — 6 context-activated workflows (test-gen, doc-gen, changelog, onboard, research, scrape) + 6 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck) + 2 tools (gcli, creating-workflows) - **6 agents** — Scoped tool access, worktree isolation, model assignment -- **7 hooks** — Safety (destructive command blocking, edit-time security patterns), observability (audit trail, slop detection, post-validation, subagent verification), optimization (RTK token compression) +- **8 hooks** — Safety (destructive command blocking, edit-time security patterns, PR gate), observability (audit trail, slop detection, post-validation, subagent verification), optimization (RTK token compression) - **Graceful degradation** — tri:* commands work with 1-3 agents depending on installed CLIs - **Goal decomposition** — Task DAG with dependency ordering and parallel execution - **Concurrency limits** — Max 3 parallel agents in multi-agent commands diff --git a/commands/status.md b/commands/status.md index 1932d12..8852fe5 100644 --- a/commands/status.md +++ b/commands/status.md @@ -25,6 +25,8 @@ echo -n "codex: " && (command -v codex && codex --version 2>/dev/null || echo "n echo -n "gemini: " && (command -v gemini && gemini --version 2>/dev/null || echo "not installed") echo -n "gh: " && (command -v gh && gh --version 2>/dev/null | head -1 || echo "not installed") echo -n "rtk: " && (command -v rtk && rtk --version 2>/dev/null || echo "not installed (optional — 60-90% token savings)") +echo -n "gcli: " && (command -v gcli >/dev/null 2>&1 && echo "installed" || echo "not installed (optional — Google Workspace: Gmail, Calendar, Drive)") +echo -n "sg: " && (command -v sg >/dev/null 2>&1 && (sg --version 2>/dev/null || echo "installed") || echo "not installed (optional — AST-based repo mapping)") echo "" echo "=== RTK Status ===" if command -v rtk >/dev/null 2>&1; then diff --git a/commands/tri-review.md b/commands/tri-review.md index fd68d9d..025eb82 100644 --- a/commands/tri-review.md +++ b/commands/tri-review.md @@ -97,6 +97,8 @@ Input: {prompt} ### Codex — if available +**Plugin (preferred):** + ``` /codex:rescue --effort high --background \ "{prompt} $(cat /tmp/tri-review-diff.txt)" @@ -104,6 +106,16 @@ Input: {prompt} Retrieve result with `/codex:result` when done. Omit `--model` to use the account default. +**CLI fallback (only if plugin not installed):** + +```bash +if [ "$HAS_CODEX_CLI" = "yes" ]; then + codex exec --full-auto "{prompt} $(cat /tmp/tri-review-diff.txt)" \ + > /tmp/tri-review-codex.txt 2>/dev/null & + CODEX_PID=$! +fi +``` + ### Gemini — if available **Plugin (preferred):** @@ -135,7 +147,7 @@ Note: Gemini CLI defaults to the best available model. Don't hardcode a model na | Agent | Method | Flags | |---|---|---| | Claude | Native background agent | `isolation: worktree`, `background: true` | -| Codex | Plugin (preferred) / CLI fallback | `/codex:rescue --background` or `codex -q` | +| Codex | Plugin (preferred) / CLI fallback | `/codex:rescue --background` or `codex exec --full-auto` | | Gemini | Plugin (preferred) / CLI fallback | `/gemini:rescue --background` or `-y` | ## Step 5: Consolidate diff --git a/hooks/hooks.json b/hooks/hooks.json index 7583f7d..7586c91 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -46,6 +46,17 @@ } ] }, + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pr-gate.sh", + "statusMessage": "PR check...", + "timeout": 5 + } + ] + }, { "matcher": "Edit|Write", "hooks": [ diff --git a/hooks/pr-gate.sh b/hooks/pr-gate.sh new file mode 100755 index 0000000..e189f67 --- /dev/null +++ b/hooks/pr-gate.sh @@ -0,0 +1,39 @@ +#!/bin/bash +# devkit PR gate hook — prompts to run pr-ready pipeline before creating a PR +# Runs on PreToolUse for Bash tool +# +# Detects `gh pr create` commands and asks the user if they want to run +# the full pr-ready pipeline first. + +INPUT=$(cat) +COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') + +# Only trigger on gh pr create +echo "$COMMAND" | grep -qE 'gh\s+pr\s+create' || exit 0 + +# Check if pr-ready already ran this session (cooldown file) +PR_GATE_FILE="/tmp/devkit-pr-gate-done" +if [ -f "$PR_GATE_FILE" ]; then + LAST=$(cat "$PR_GATE_FILE" 2>/dev/null) + NOW=$(date +%s 2>/dev/null) + if [ -n "$LAST" ] && [ -n "$NOW" ]; then + ELAPSED=$(( NOW - LAST )) 2>/dev/null || ELAPSED=0 + if [ "$ELAPSED" -lt 600 ] 2>/dev/null; then + # Pipeline already ran recently, allow the PR creation + exit 0 + fi + fi +fi + +# Set cooldown so this only fires once +date +%s > "$PR_GATE_FILE" 2>/dev/null + +# Ask the user +jq -n '{ + hookSpecificOutput: { + hookEventName: "PreToolUse", + permissionDecision: "ask", + permissionDecisionReason: "PR creation detected — want to run /devkit:pr-ready first? (lint, test, security, DRY review, changelog). Say yes to run the pipeline, or approve to skip and create the PR directly." + } +}' +exit 0 diff --git a/manifest.json b/manifest.json index dec38a1..c636c19 100644 --- a/manifest.json +++ b/manifest.json @@ -13,18 +13,12 @@ "commands/self-lint.md", "commands/self-perf.md", "commands/self-migrate.md", - "commands/test-gen.md", - "commands/doc-gen.md", "commands/pr-ready.md", - "commands/onboard.md", - "commands/changelog.md", "commands/workflow.md", "commands/status.md", "commands/bugfix.md", "commands/feature.md", "commands/refactor.md", - "commands/research.md", - "commands/scrape.md", "commands/decompose.md", "commands/audit.md", "commands/pr-monitor.md", @@ -36,7 +30,15 @@ "skills/dry.md", "skills/yagni.md", "skills/creating-workflows.md", - "skills/stuck.md" + "skills/stuck.md", + "skills/gcli.md", + "skills/dont-reinvent.md", + "skills/changelog.md", + "skills/onboard.md", + "skills/doc-gen.md", + "skills/test-gen.md", + "skills/scrape.md", + "skills/research.md" ], "agents": [ "agents/reviewer.md", diff --git a/commands/changelog.md b/skills/changelog.md similarity index 91% rename from commands/changelog.md rename to skills/changelog.md index 4dd2704..dee1f0c 100644 --- a/commands/changelog.md +++ b/skills/changelog.md @@ -1,6 +1,6 @@ --- name: devkit:changelog -description: Generate a structured changelog from git history. Categorizes commits and formats for release notes. +description: Generate a structured changelog from git history — use when asked to create a changelog, release notes, or summarize what changed between versions/tags/branches. --- # Changelog Generation diff --git a/commands/doc-gen.md b/skills/doc-gen.md similarity index 90% rename from commands/doc-gen.md rename to skills/doc-gen.md index f93ac58..069543f 100644 --- a/commands/doc-gen.md +++ b/skills/doc-gen.md @@ -1,6 +1,6 @@ --- name: devkit:doc-gen -description: Generate documentation for target code. Analyzes exports, API surface, and usage patterns to produce structured docs. +description: Generate documentation for code — use when asked to document a module, generate API docs, create a README for code, or write reference documentation. --- # Documentation Generation diff --git a/skills/dont-reinvent.md b/skills/dont-reinvent.md new file mode 100644 index 0000000..b5d3652 --- /dev/null +++ b/skills/dont-reinvent.md @@ -0,0 +1,59 @@ +--- +name: devkit:dont-reinvent +description: Don't reinvent the wheel — use existing libraries, tools, and stdlib before building custom solutions. Every custom solution is maintenance burden. +--- + +# Don't Reinvent the Wheel + +Before writing any non-trivial utility, helper, or tool — check if it already exists. + +## The Search Order + +1. **Language stdlib / builtins** — `path.join()`, `os.path`, `filepath.Join()` exist. Don't write your own. +2. **Framework built-ins** — most frameworks have solutions for routing, validation, auth, caching. Use them. +3. **Established packages** — if there's a well-maintained package with meaningful adoption and recent commits, prefer it over custom code. +4. **Existing tools / plugins / MCP servers** — before building a new CLI wrapper or integration, check if one exists. Run a quick search. +5. **Internal codebase** — search the project for existing utilities before creating new ones. Someone may have already solved this. + +Only build custom when none of the above genuinely fit. + +## Why This Matters + +Every custom solution is code **you maintain forever**: +- Bug fixes are your problem +- Edge cases are your problem +- Updates when dependencies change are your problem +- Documentation is your problem + +A well-maintained library handles all of this for you. The 20 minutes you "save" by writing it yourself costs hours in future maintenance. + +## When Custom Is Justified + +- The existing solutions don't fit and adapting them is harder than building +- The existing solutions are unmaintained (no commits in 12+ months, unresolved security issues) +- The scope is truly trivial (a 3-line helper doesn't need a dependency) +- Performance requirements rule out general-purpose solutions (measure first, don't assume) +- Security requirements demand full control over the implementation + +## Red Flags You're Reinventing + +- Writing a date parser, URL parser, retry wrapper, or logger from scratch +- Building a custom HTTP client wrapper around fetch/axios +- Writing string manipulation utilities that exist in lodash/underscore/stdlib +- Creating a custom config file format instead of using JSON/YAML/TOML +- Building a task queue when BullMQ/Celery/existing solutions exist +- Writing a custom test framework instead of using the ecosystem standard + +## Evaluating Existing Solutions + +Before adopting a dependency, check: + +- **Last commit date** — no commits in 12+ months is a warning sign +- **Open issues** — many unresolved issues with no maintainer response suggests abandonment +- **Downloads / stars** — social proof that others rely on it +- **License compatibility** — GPL in an MIT project is a problem +- **Bundle size** — don't add a 500KB dependency for one function (use the function directly) + +## The Maintenance Test + +Before writing custom code, ask: "Am I willing to maintain this for the life of the project?" If the answer is no, find an existing solution. If no existing solution fits, keep the custom code as simple as possible — the less code you write, the less you maintain. diff --git a/skills/gcli.md b/skills/gcli.md new file mode 100644 index 0000000..852b48d --- /dev/null +++ b/skills/gcli.md @@ -0,0 +1,110 @@ +--- +name: devkit:gcli +description: Google Workspace CLI (Gmail, Calendar, Drive) via gcli — use --for-ai flag for token-efficient structured output. +--- + +# gcli — Google Workspace CLI + +Single binary for Gmail, Calendar, and Drive. Always use `--for-ai` for structured, token-efficient output. + +## Confirmation Required + +**NEVER** send, reply, forward, or delete email/calendar events without explicit user confirmation of the recipient(s), subject, and body. Always show the user what will be sent and wait for approval before executing. The same applies to `cal create`, `cal edit`, `cal delete`, and `drive upload`. + +## Prerequisites + +Before using any gcli command, verify it is installed: + +```bash +command -v gcli >/dev/null 2>&1 && echo "gcli: installed" || echo "gcli: not installed — install from https://github.com/AryaLabsHQ/gcli and run 'gcli login'" +``` + +If gcli is not installed, tell the user and stop. Do not attempt gcli commands without this check. + +## Gmail + +```bash +# List inbox (default 20) +gcli mail list --for-ai +gcli mail list 10 --unread --for-ai + +# Read a thread +gcli mail get --for-ai + +# Search +gcli mail search "from:boss subject:review" --for-ai + +# Send +gcli mail send -t "user@example.com" -s "Subject" --body-file msg.txt + +# Reply (use thread-id from list/search) +gcli mail reply --body-file reply.txt +gcli mail reply --all --body-file reply.txt + +# Forward / mark +gcli mail forward -t "other@example.com" +gcli mail mark --read +gcli mail mark --trash +``` + +## Calendar + +```bash +# Today's events +gcli cal list --for-ai + +# Next 7 days +gcli cal list 7 --for-ai + +# All calendars +gcli cal list 7 --all-calendars --for-ai + +# Event details +gcli cal get --for-ai + +# Create +gcli cal create "Meeting" -s "tomorrow 2pm" -d "1h" --attendee "person@example.com" + +# Edit / delete +gcli cal edit -s "tomorrow 3pm" +gcli cal delete +``` + +## Drive + +```bash +# List root +gcli drive list --for-ai + +# List folder +gcli drive list "path/to/folder" --for-ai + +# Search +gcli drive search "quarterly report" --for-ai + +# Shared files +gcli drive list -s --for-ai + +# Download / upload +gcli drive download "path/to/file" -o ./local-file +gcli drive upload ./local-file "path/to/folder" + +# Info / permissions +gcli drive info "path/to/file" --for-ai +gcli drive permissions "path/to/file" --for-ai +``` + +## Composing Emails + +When writing email body: +1. Create a temp file: `tmp=$(mktemp)` +2. Write content to it +3. Use `--body-file "$tmp"` to send — avoids shell escaping issues +4. Clean up: `rm -f "$tmp"` + +## Tips + +- Thread IDs from `mail list` and `mail search` feed into `mail get`, `mail reply`, `mail forward` +- Event IDs from `cal list` feed into `cal get`, `cal edit`, `cal delete` +- `--for-ai` strips HTML and formats for LLM consumption — always use it for reads +- Attachments: `-A file1.pdf -A file2.pdf` (repeatable) diff --git a/commands/onboard.md b/skills/onboard.md similarity index 93% rename from commands/onboard.md rename to skills/onboard.md index d4f6368..8a646ca 100644 --- a/commands/onboard.md +++ b/skills/onboard.md @@ -1,6 +1,6 @@ --- name: devkit:onboard -description: Generate a codebase onboarding guide. Analyzes architecture, key files, patterns, and gotchas to help new contributors get up to speed. +description: Generate a codebase onboarding guide — use when asked to explain this codebase, help understand the architecture, give a tour of the repo, or onboard a new contributor. --- # Codebase Onboarding diff --git a/commands/research.md b/skills/research.md similarity index 94% rename from commands/research.md rename to skills/research.md index 27de701..5907ee9 100644 --- a/commands/research.md +++ b/skills/research.md @@ -1,6 +1,6 @@ --- name: devkit:research -description: Deep research workflow — clarify question, parallel web search, analyze sources, synthesize findings. +description: Deep research workflow — use when asked to research a topic, do a deep dive, investigate options, compare approaches, or find the best solution to a technical question. --- # Research Workflow diff --git a/commands/scrape.md b/skills/scrape.md similarity index 95% rename from commands/scrape.md rename to skills/scrape.md index e3f0917..b6c32b3 100644 --- a/commands/scrape.md +++ b/skills/scrape.md @@ -1,6 +1,6 @@ --- name: devkit:scrape -description: Scrape a URL and return clean Markdown (or Markdown-in-JSON). Uses Jina Reader, Firecrawl, or raw WebFetch. +description: Scrape a URL to clean Markdown — use when asked to scrape, fetch, extract content from, or read a webpage and convert it to Markdown. Uses Jina Reader, Firecrawl, or WebFetch. --- # Web Scrape to Markdown diff --git a/commands/test-gen.md b/skills/test-gen.md similarity index 91% rename from commands/test-gen.md rename to skills/test-gen.md index 6cbd6dd..189c74a 100644 --- a/commands/test-gen.md +++ b/skills/test-gen.md @@ -1,6 +1,6 @@ --- name: devkit:test-gen -description: Generate a comprehensive test suite for target files. Detects framework, writes tests, runs them, fixes failures — iterates until green. +description: Generate tests for code — use when asked to write tests, create a test suite, add test coverage, or generate unit/integration tests for a file or module. --- # Test Generation