Skip to content

docs(install): per-agent install matrix + first-run welcome #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rohitg00 merged 4 commits into from
May 27, 2026
Merged

docs(install): per-agent install matrix + first-run welcome #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7e2342a
docs(install): per-agent install matrix + first-run welcome
rohitg00 May 27, 2026
f9a328c
docs(install): remove unpublished marketplace commands
rohitg00 May 27, 2026
e8aac47
fix(skillkit): make 'skillkit install' actually work
rohitg00 May 27, 2026
089f579
docs(readme): link skillkit#129 tracking issue
rohitg00 May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 53 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,31 +56,74 @@ Session 50: Correction rate near zero. Wiki has 200 cited claims.

## Install

Pro Workflow is published in two places: the Claude Code plugin marketplace (native), and SkillKit (cross-agent translator). Other agents do not have first-class plugins yet — SkillKit translates the skill bundle into each agent's native skill format.

### Claude Code (native)

```bash
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow
```

<details>
<summary>Other install methods</summary>
### Cursor, Codex, Copilot CLI, Droid, Gemini CLI, OpenCode, and 26 more (via SkillKit)

SkillKit translates the 34 skills + 22 commands into each agent's native skill format and drops them in the right config directory.

```bash
# Cursor
/add-plugin pro-workflow
npx skillkit install rohitg00/pro-workflow --agent <name> --force
```

# Any agent via SkillKit
npx skillkit install pro-workflow
Notes:

- Use `rohitg00/pro-workflow` (the GitHub form), not the bare name &mdash; `skillkit install` resolves providers from `owner/repo`, not marketplace slugs.
- `--force` is currently required: SkillKit's security scanner has open false positives on standard Node patterns (`child_process` imports, `Bearer ${env}` template literals) that block legit skills like `survey-generator` and `safe-mode`. Tracked at [`skillkit#129`](https://github.com/rohitg00/skillkit/issues/129).

# Manual
Supported `<name>` values: `cursor`, `codex`, `gemini-cli`, `opencode`, `github-copilot`, `droid` (factory), `antigravity`, `amp`, `clawdbot`, `cline`, `codebuddy`, `commandcode`, `continue`, `crush`, `goose`, `kilo`, `kiro-cli`, `mcpjam`, `mux`, `neovate`, `openhands`, `pi`, `qoder`, `qwen`, `roo`, `trae`, `universal`, `vercel`, `windsurf`, `zencoder`. Pass `--agent universal` for a portable bundle.

After install, run `skillkit sync` to register the skills with the target agent's config.

<details>
<summary>Manual install (any agent, any OS)</summary>

If neither path works for your setup, clone and copy the bundle directly. Adjust the destination to your agent's skill directory (e.g. `~/.cursor/rules/`, `~/.gemini/extensions/`, etc.).

```bash
git clone https://github.com/rohitg00/pro-workflow.git /tmp/pw
cp -r /tmp/pw/templates/split-claude-md/* ./.claude/
cd /tmp/pw && npm install && npm run build

# Build SQLite-backed components
cd ~/.claude/plugins/*/pro-workflow && npm install && npm run build
cp -r /tmp/pw/templates/split-claude-md/* ./.claude/
cp -r /tmp/pw/skills ~/.claude/skills/
cp -r /tmp/pw/commands ~/.claude/commands/
cp /tmp/pw/hooks/hooks.json ~/.claude/hooks.json
```

</details>

### First-run smoke test

```bash
/doctor # confirms SQLite store, hooks, skills load
/wrap-up # runs the end-of-session ritual (no-op on fresh install)
```

If `/doctor` reports `KB: missing`, run `cd ~/.claude/plugins/*/pro-workflow && npm install && npm run build` &mdash; the SQLite components need a build step a handful of marketplaces skip.

---

## What to type first

After install you have **34 auto-trigger skills** and **22 slash commands**. You don't need to memorize them; the agent picks the right skill from your prompt. The five commands below cover 80% of daily use:

| When | Command | What it does |
|---|---|---|
| **Wrong correction repeats** | `/learn-rule` | Capture the correction as a rule. Loaded on every future `SessionStart`. |
| **End of a coding session** | `/wrap-up` | Audit changes, persist learnings, write a handoff doc. |
| **Researching a topic** | `/wiki init <slug>` | Spin up a persistent FTS5 wiki. Auto-injected when you mention the topic later. |
| **Stuck on a hard bug** | `/develop` | Research &rarr; Plan &rarr; Implement phases with validation gates. |
| **Before a PR** | `/smart-commit` | Quality gates, staged review, conventional commit message. |

Full list: [`commands/`](./commands) &middot; [`skills/`](./skills) &middot; [`/list`](./commands/list.md) inside any session.

---

## 60-second tour
Expand Down
18 changes: 17 additions & 1 deletion scripts/session-start.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,23 @@ async function main() {
// Not a git repo or git not available
}

log('[ProWorkflow] Ready. Use /wrap-up before ending, /learn to capture corrections.');
const stateDir = path.join(os.homedir(), '.pro-workflow');
const firstRunFlag = path.join(stateDir, '.welcomed');
if (!fs.existsSync(firstRunFlag)) {
try { fs.mkdirSync(stateDir, { recursive: true }); } catch (e) {}
log('');
log('[ProWorkflow] First run detected. Five commands to know:');
log(' /learn-rule capture a correction so it never repeats');
log(' /wrap-up end-of-session ritual (audit + persist + handoff)');
log(' /wiki init start a persistent FTS5 research wiki');
log(' /develop research -> plan -> implement with gates');
log(' /smart-commit quality-gated conventional commit');
log('[ProWorkflow] Run /doctor to verify install. Full list: /list');
log('');
try { fs.writeFileSync(firstRunFlag, new Date().toISOString()); } catch (e) {}
} else {
Comment on lines +126 to +137

@coderabbitai coderabbitai Bot May 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Don’t silently swallow first-run marker write failures.

If directory creation or marker write fails, users will repeatedly see “first run” with no clue why. Log a warning in these catch blocks so setup issues are diagnosable.

Suggested patch 
-    try { fs.mkdirSync(stateDir, { recursive: true }); } catch (e) {}
+    try { fs.mkdirSync(stateDir, { recursive: true }); } catch (e) {
+      log(`[ProWorkflow] Warning: could not create state dir at ${stateDir}: ${e.message}`);
+    }
@@
-    try { fs.writeFileSync(firstRunFlag, new Date().toISOString()); } catch (e) {}
+    try { fs.writeFileSync(firstRunFlag, new Date().toISOString()); } catch (e) {
+      log(`[ProWorkflow] Warning: could not persist welcome flag at ${firstRunFlag}: ${e.message}`);
+    }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
try { fs.mkdirSync(stateDir, { recursive: true }); } catch (e) {}
log('');
log('[ProWorkflow] First run detected. Five commands to know:');
log(' /learn-rule capture a correction so it never repeats');
log(' /wrap-up end-of-session ritual (audit + persist + handoff)');
log(' /wiki init start a persistent FTS5 research wiki');
log(' /develop research -> plan -> implement with gates');
log(' /smart-commit quality-gated conventional commit');
log('[ProWorkflow] Run /doctor to verify install. Full list: /list');
log('');
try { fs.writeFileSync(firstRunFlag, new Date().toISOString()); } catch (e) {}
} else {
try { fs.mkdirSync(stateDir, { recursive: true }); } catch (e) {
log(`[ProWorkflow] Warning: could not create state dir at ${stateDir}: ${e.message}`);
}
log('');
log('[ProWorkflow] First run detected. Five commands to know:');
log(' /learn-rule capture a correction so it never repeats');
log(' /wrap-up end-of-session ritual (audit + persist + handoff)');
log(' /wiki init start a persistent FTS5 research wiki');
log(' /develop research -> plan -> implement with gates');
log(' /smart-commit quality-gated conventional commit');
log('[ProWorkflow] Run /doctor to verify install. Full list: /list');
log('');
try { fs.writeFileSync(firstRunFlag, new Date().toISOString()); } catch (e) {
log(`[ProWorkflow] Warning: could not persist welcome flag at ${firstRunFlag}: ${e.message}`);
}
} else {
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/session-start.js` around lines 126 - 137, The try/catch around
fs.mkdirSync(stateDir, { recursive: true }) and fs.writeFileSync(firstRunFlag,
...) currently swallow errors; update both catch blocks to log a warning
including the error and the path (stateDir or firstRunFlag) so failures are
visible. In each catch, call the existing log function (or console.warn) with a
clear message like "[ProWorkflow] Warning: failed to create stateDir <path>:
<error>" and "[ProWorkflow] Warning: failed to write firstRunFlag <path>:
<error>" so operators can diagnose setup problems.

log('[ProWorkflow] Ready. Use /wrap-up before ending, /learn to capture corrections.');
}

process.exit(0);
}
Expand Down
2 changes: 1 addition & 1 deletion skills/auto-setup/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Run each command with `--version` or `--help` to confirm availability. Report mi

Generate a `.claude/settings.json` with:
- Quality gate commands for the detected project type
- Safe permission rules (read-only tools auto-approved)
- Suggested permission rules (user reviews and approves)
- Hook configuration for the project

## Output
Expand Down
8 changes: 4 additions & 4 deletions skills/permission-tuner/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ cat ~/.claude/settings.json 2>/dev/null | grep -A 20 "permissions"

### Step 2: Identify Safe Patterns

**Auto-approve candidates** (low risk):
**Allow-list candidates** (low risk):
- `Read` — all file reads (read-only, no side effects)
- `Glob` — file pattern matching (read-only)
- `Grep` — content search (read-only)
Expand All @@ -44,14 +44,14 @@ cat ~/.claude/settings.json 2>/dev/null | grep -A 20 "permissions"
- `Bash(npm run lint*)` — linting
- `Bash(npm run typecheck*)` — type checking

**Ask candidates** (medium risk — auto-approve only if user confirms):
**Ask candidates** (medium risk — prompt user every time):
- `Edit` — file modifications
- `Write` — new file creation
- `Bash(git add*)` — staging changes
- `Bash(git commit*)` — creating commits
- `Bash(npm install*)` — dependency changes

Comment on lines +47 to 53

@coderabbitai coderabbitai Bot May 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Resolve medium-risk policy conflict with the report example.

Line 47 says medium-risk actions should prompt every time, but the report example still auto-approves medium-risk operations (Line 98 onward). Please align the output example to “keep asking” for medium-risk items so the guidance is consistent and safer.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/permission-tuner/SKILL.md` around lines 47 - 53, The SKILL.md “Ask
candidates” policy lists medium-risk actions (Edit, Write, Bash git/npm) that
must prompt every time, but the report example later still auto-approves them;
update the example section (the report example starting around the “report
example” block) so that any medium-risk action listed under the “Ask candidates”
header triggers a prompt/confirmation flow rather than
auto-approval—specifically change the example outputs for Edit, Write, Bash(git
add*/git commit*/npm install*) to show a prompt or “awaiting user confirmation”
state and reflect the decision only after explicit approval, ensuring the
example behavior matches the policy text.

**Never auto-approve** (high risk):
**Deny-list candidates** (high risk):
- `Bash(git push*)` — affects remote
- `Bash(git reset --hard*)` — destructive
- `Bash(rm -rf*)` — destructive
Expand Down Expand Up @@ -112,7 +112,7 @@ Estimated prompts saved per session: ~[N]

## Rules

- Never auto-approve destructive operations
- Destructive operations must stay in the deny list
- Always present rules for user approval before applying
- Group rules by risk level (safe/medium/dangerous)
- Include estimated prompt savings
2 changes: 1 addition & 1 deletion skills/pro-workflow/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -452,7 +452,7 @@ For features touching >5 files or needing architecture decisions:
3. **Implement** → executes plan step by step with quality gates every 5 edits
4. **Review** → reviewer agent checks for security, logic, quality

Never skip phases. Never proceed without approval between phases.
All four phases run in order. Each phase requires explicit user approval before the next phase begins.

### Agent Skills (Preloaded)

Expand Down
2 changes: 1 addition & 1 deletion skills/safe-mode/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Intercepts Bash commands before execution. Warns on dangerous patterns but does
| `git clean -f` | Untracked file deletion |
| `git checkout .` / `git restore .` | Discard all changes |
| `chmod 777` | World-writable permissions |
| `curl \| sh` / `wget \| sh` | Piped remote execution |
| `curl` or `wget` piped to a shell | Piped remote execution |
| `> /dev/sda` / `dd if=` | Disk-level operations |
| `:(){ :\|:& };:` | Fork bombs |
| `sudo rm` | Elevated deletion |
Expand Down