PRD: sh1pt CLI — Safe GitHub Actions + Agent Skills Installer

# PRD: sh1pt CLI — Safe GitHub Actions + Agent Skills Installer

## 1. Product Summary

**sh1pt CLI** is a developer command-line tool for safely installing, auditing, and updating GitHub Actions, repo automation, and AI-agent skills across connected GitHub repositories.

The product is inspired by Google Chrome's Modern Web Guidance CLI model, where users can discover and install coding-agent guidance, but sh1pt expands the concept into a broader **safe automation installer** for GitHub workflows, repo hardening, security scans, deployment workflows, and AI coding instructions.

The core principle:

> sh1pt installs trusted automation into repositories by generating reviewable diffs and pull requests, not by blindly executing remote scripts.

This avoids turning the CLI into a supply-chain security hole while still making it easy for developers, agencies, and AI agents to add useful repo automation.

---

## 2. Problem

Developers want to add useful GitHub Actions and automation to their repositories, but the current process is messy and risky:

- Copying random workflow YAML from blog posts is error-prone.
- Many GitHub Actions ask for overly broad permissions.
- Actions are often pinned to `main` or `master`, creating supply-chain risk.
- Users do not know what secrets, permissions, or files an action requires.
- AI agents may modify repos without clear review boundaries.
- Agencies and solo developers need repeatable automation across many repos.
- There is no simple “app store” style installer for repo automation that defaults to safe reviewable changes.

sh1pt can solve this by becoming a **trusted registry + CLI + GitHub PR installer** for repo automation.

---

## 3. Goals

### Primary Goals

- Provide a CLI for discovering and installing trusted GitHub Actions.
- Generate reviewable diffs before writing files.
- Prefer opening pull requests instead of mutating default branches directly.
- Provide a manifest-based action package format.
- Prevent arbitrary remote code execution during install.
- Provide a repo workflow security auditor.
- Support sh1pt-hosted and community action packages.
- Support AI-agent skill installation into common agent instruction files.

### Secondary Goals

- Support sh1pt.com cloud installation flows.
- Allow agencies to apply the same automation pack across multiple repos.
- Support paid action packs and security automation bundles.
- Create a foundation for an “actions store” inside sh1pt.com.
- Allow bots and AI agents to safely propose automation changes via PRs.

---

## 4. Non-Goals

For MVP, sh1pt CLI will **not**:

- Execute arbitrary remote install scripts.
- Automatically run installed workflows locally.
- Write directly to protected branches by default.
- Manage all GitHub repository settings.
- Replace GitHub Actions Marketplace.
- Provide a full CI/CD platform.
- Store repository secrets directly in workflow files.
- Install untrusted third-party packages without warnings.

---

## 5. Target Users

### 5.1 Solo Developers

Developers who want to quickly add useful repo automation without manually writing workflow YAML.

### 5.2 Agencies

Agencies managing many client repos that need repeatable security, deploy, linting, and release workflows.

### 5.3 Open Source Maintainers

Maintainers who want safe PR-based automation installs for community projects.

### 5.4 AI Coding Agent Users

Users of Claude Code, Gemini CLI, OpenClaw, Codex, Cursor, Copilot, Goose, and similar tools who want agent skills and repo instructions installed consistently.

### 5.5 sh1pt Cloud Users

Users who prefer a web UI to connect GitHub repos and install workflow packs through generated pull requests.

---

## 6. Product Positioning

sh1pt CLI is:

> A safe CLI and app store for installing GitHub Actions, repo automation, and AI-agent skills through reviewable pull requests.

Possible taglines:

- “Ship safer automation.”
- “GitHub Actions installs without the supply-chain footgun.”
- “An app store for repo automation.”
- “Install workflows by PR, not by pipe-to-bash.”
- “Trusted automation for humans and agents.”

---

## 7. Core Concepts

## 7.1 Action Package

An **action package** is a declarative bundle that installs one or more files into a repo.

Example use cases:

- Security scanning workflow
- Dependency review workflow
- Release drafter workflow
- Docker build workflow
- Static site deployment workflow
- Vulnerability scanner
- PR labeler
- AI code review workflow

Action packages must use a manifest file and must not execute arbitrary install scripts.

## 7.2 Skill Package

A **skill package** installs guidance for coding agents.

Example destinations:

- `AGENTS.md`
- `CLAUDE.md`
- `.github/copilot-instructions.md`
- `.cursor/rules/*`
- `.codex/*`
- `.openclaw/*`
- `.goose/*`

Skill packages can include markdown guidance, coding standards, security rules, framework conventions, and task-specific instructions.

## 7.3 Registry

The sh1pt registry stores metadata for available actions and skills.

Registry package types:

- Official sh1pt packages
- Profullstack packages
- Verified publisher packages
- Community packages
- Experimental packages
- Private organization packages

## 7.4 Install Plan

Before modifying anything, the CLI generates an install plan showing:

- Files to create
- Files to modify
- GitHub permissions requested
- Secrets required
- Third-party actions used
- Whether versions are pinned
- Risk level
- Recommended install mode

## 7.5 Reviewable Install

The default install behavior should be:

1. Generate install plan.
2. Show diff.
3. Ask for confirmation.
4. Create branch.
5. Commit changes.
6. Open pull request.

Direct writes should be explicit and discouraged for risky packages.

---

## 8. CLI Command Design

## 8.1 Global Commands

```bash
sh1pt --help
sh1pt --version
sh1pt init
sh1pt login
sh1pt logout
sh1pt whoami
```

## 8.2 Repository Commands

```bash
sh1pt repo detect
sh1pt repo connect
sh1pt repo status
```

## 8.3 Action Discovery

```bash
sh1pt actions list
sh1pt actions search "security scan"
sh1pt actions info vu1nz-scan
```

## 8.4 Action Planning

```bash
sh1pt actions plan vu1nz-scan
sh1pt actions plan vu1nz-scan --repo profullstack/sh1pt
```

Expected output:

```txt
Action: vu1nz-scan
Publisher: profullstack
Version: 0.1.0
Trust level: verified

Files to create:
  .github/workflows/vu1nz-scan.yml

Permissions requested:
  contents: read
  security-events: write

Secrets required:
  none

Third-party actions:
  actions/checkout@v4

Warnings:
  none

Risk level:
  medium

Recommended install mode:
  pull request
```

## 8.5 Action Installation

```bash
sh1pt actions install vu1nz-scan --dry-run
sh1pt actions install vu1nz-scan --pr
sh1pt actions install vu1nz-scan --branch sh1pt/install-vu1nz-scan
sh1pt actions install vu1nz-scan --yes
```

Default behavior should be equivalent to:

```bash
sh1pt actions install vu1nz-scan --pr
```

## 8.6 Action Updates

```bash
sh1pt actions outdated
sh1pt actions update
sh1pt actions update vu1nz-scan --pr
```

## 8.7 Action Audit

```bash
sh1pt actions audit
sh1pt actions audit --strict
sh1pt actions audit --json
```

Audit should detect:

- `uses: owner/action@main`
- `uses: owner/action@master`
- `permissions: write-all`
- Missing explicit permissions block
- `pull_request_target` usage
- `curl | bash`
- `wget | bash`
- Unpinned Docker images
- Untrusted third-party actions
- Secrets exposed to pull requests
- Workflows triggered by unsafe events
- Excessive token permissions

## 8.8 Skill Commands

```bash
sh1pt skills list
sh1pt skills search "modern web guidance"
sh1pt skills info modern-web
sh1pt skills retrieve modern-web
sh1pt skills install modern-web
sh1pt skills install modern-web --target claude
sh1pt skills install modern-web --target copilot
sh1pt skills install modern-web --target agents-md
```

## 8.9 Pack Commands

Packs install multiple actions or skills together.

```bash
sh1pt packs list
sh1pt packs info repo-security-baseline
sh1pt packs install repo-security-baseline --pr
```

Example packs:

- `repo-security-baseline`
- `nodejs-ci`
- `sveltekit-ci`
- `nextjs-ci`
- `docker-release`
- `open-source-maintainer`
- `ai-agent-ready`

---

## 9. Example MVP Action Package

Initial package:

```txt
packages/actions/vu1nz-scan/
  sh1pt.action.json
  README.md
  workflows/
    vu1nz-scan.yml
```

Manifest:

```json
{
  "name": "vu1nz-scan",
  "publisher": "profullstack",
  "type": "github-action",
  "version": "0.1.0",
  "title": "vu1nz Security Scan",
  "description": "Adds a GitHub Actions workflow for running vu1nz security scans.",
  "trustLevel": "verified",
  "files": [
    {
      "path": ".github/workflows/vu1nz-scan.yml",
      "template": "workflows/vu1nz-scan.yml"
    }
  ],
  "permissions": {
    "contents": "read",
    "security-events": "write"
  },
  "secrets": [],
  "thirdPartyActions": [
    {
      "uses": "actions/checkout@v4",
      "pinned": false,
      "trusted": true
    }
  ],
  "requiresConfirmation": true,
  "recommendedInstallMode": "pr"
}
```

Workflow template:

```yaml
name: vu1nz Scan

on:
  push:
    branches:
      - main
      - master
  pull_request:

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run vu1nz scan
        run: |
          echo "TODO: run vu1nz scan"
```

---

## 10. Security Requirements

## 10.1 No Arbitrary Install Scripts

Action and skill packages must be declarative.

Disallowed:

```json
{
  "postinstall": "node install.js"
}
```

Disallowed:

```bash
curl https://example.com/install.sh | bash
```

Allowed:

- Copying template files
- Rendering safe templates
- Creating branches
- Opening pull requests
- Updating known files after diff review

## 10.2 Pull Request First

The recommended default is always PR mode:

```bash
sh1pt actions install vu1nz-scan --pr
```

Direct write mode requires an explicit flag:

```bash
sh1pt actions install vu1nz-scan --write
```

For untrusted packages, direct write mode should be blocked unless the user passes:

```bash
--allow-untrusted --write
```

## 10.3 Diff Preview Required

Every install must generate a diff before changes are applied.

The CLI must show:

- New files
- Modified files
- Deleted files, if any
- Permissions being introduced
- Secrets being referenced
- Workflow triggers being added

## 10.4 Permission Minimization

The CLI should reject or warn heavily on:

```yaml
permissions: write-all
```

Preferred default:

```yaml
permissions:
  contents: read
```

Additional permissions must be justified in the package manifest.

## 10.5 Version Pinning

The audit system should warn on:

```yaml
uses: some/action@main
uses: some/action@master
```

Accepted:

```yaml
uses: actions/checkout@v4
```

High-security mode should recommend commit SHA pinning:

```yaml
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
```

## 10.6 Secret Safety

The CLI must never:

- Print secret values
- Commit `.env` files
- Write literal secrets into workflow YAML
- Upload secrets to sh1pt without explicit user consent

Allowed workflow reference:

```yaml
env:
  SH1PT_API_KEY: ${{ secrets.SH1PT_API_KEY }}
```

## 10.7 Local Execution Safety

Installing and running are separate operations.

Install:

```bash
sh1pt actions install vu1nz-scan --pr
```

Run:

```bash
sh1pt actions run vu1nz-scan --sandbox
```

The MVP does not need local execution.

## 10.8 Trust Levels

Packages should be labeled as:

- `official`
- `verified`
- `community`
- `experimental`
- `untrusted`

Untrusted packages require explicit confirmation and should default to dry-run mode only.

---

## 11. Registry Design

## 11.1 Registry Structure

```txt
packages/
  registry/
    actions.json
    skills.json
    packs.json
  actions/
    vu1nz-scan/
      sh1pt.action.json
      README.md
      workflows/
        vu1nz-scan.yml
  skills/
    modern-web/
      sh1pt.skill.json
      guides/
        modern-web.md
  packs/
    repo-security-baseline/
      sh1pt.pack.json
```

## 11.2 Registry Metadata

`actions.json`:

```json
[
  {
    "name": "vu1nz-scan",
    "publisher": "profullstack",
    "version": "0.1.0",
    "description": "Adds vu1nz security scanning to GitHub Actions.",
    "trustLevel": "verified",
    "category": "security",
    "path": "packages/actions/vu1nz-scan/sh1pt.action.json"
  }
]
```

## 11.3 Registry Sources

MVP registry can be loaded from:

- Local repo path
- GitHub raw URL
- sh1pt.com API

Recommended MVP order:

1. Local bundled registry
2. GitHub registry URL
3. sh1pt.com hosted registry

---

## 12. Technical Architecture

## 12.1 Stack

Use the usual project style:

- Node.js
- ESM
- Vanilla JavaScript
- pnpm
- No TypeScript for MVP
- Minimal dependencies

## 12.2 Suggested Repo Layout

```txt
packages/
  cli/
    package.json
    bin/
      sh1pt.js
    src/
      commands/
        actions.js
        skills.js
        packs.js
        repo.js
        audit.js
      lib/
        registry.js
        manifest.js
        templates.js
        git.js
        github.js
        security.js
        diff.js
        logger.js
  registry/
    actions.json
    skills.json
    packs.json
  actions/
    vu1nz-scan/
      sh1pt.action.json
      README.md
      workflows/
        vu1nz-scan.yml
  skills/
    modern-web/
      sh1pt.skill.json
      guides/
        modern-web.md
```

## 12.3 CLI Package

`packages/cli/package.json`:

```json
{
  "name": "@profullstack/sh1pt-cli",
  "version": "0.1.0",
  "type": "module",
  "bin": {
    "sh1pt": "./bin/sh1pt.js"
  },
  "scripts": {
    "dev": "node ./bin/sh1pt.js",
    "test": "node --test"
  },
  "dependencies": {}
}
```

## 12.4 CLI Entry

`bin/sh1pt.js`:

```js
#!/usr/bin/env node

import { run } from '../src/index.js';

run(process.argv.slice(2)).catch((err) => {
  console.error(err.message || err);
  process.exit(1);
});
```

---

## 13. GitHub Integration

## 13.1 MVP Options

The CLI can support either:

1. GitHub CLI integration via `gh`
2. GitHub token from environment
3. sh1pt cloud auth token

Recommended MVP:

- First support local git branch + commit.
- Then support PR creation through `gh` if available.
- Later support direct GitHub API integration.

## 13.2 PR Install Flow

```txt
1. Detect current git repo.
2. Confirm clean working tree or ask user to continue.
3. Load action manifest.
4. Render files into temp directory.
5. Generate diff.
6. Show install plan.
7. Create branch: sh1pt/install-<action-name>
8. Write files.
9. Commit changes.
10. Open PR using gh CLI or GitHub API.
```

## 13.3 PR Title

```txt
Install sh1pt action: vu1nz-scan
```

## 13.4 PR Body

```md
## Summary

This PR installs the `vu1nz-scan` sh1pt action.

## Files Added

- `.github/workflows/vu1nz-scan.yml`

## Permissions Requested

- `contents: read`
- `security-events: write`

## Secrets Required

None.

## Risk Level

Medium.

Generated by sh1pt CLI.
```

---

## 14. sh1pt Cloud Integration

The cloud version can expose the same registry and install flow through a web UI.

## 14.1 User Flow

1. User logs into sh1pt.com.
2. User connects GitHub.
3. User selects repo.
4. User searches action store.
5. User selects action or pack.
6. sh1pt shows install plan.
7. sh1pt opens a pull request.
8. User reviews and merges in GitHub.

## 14.2 Paid Features

Potential paid features:

- Private action registry
- Organization-wide automation packs
- Scheduled workflow audits
- Auto-PR updates for outdated actions
- High-security pinning mode
- Custom agency-branded packs
- Secret scanning integrations
- Dependency scanning integrations
- AI-generated workflow recommendations
- Client repo automation dashboard

---

## 15. MVP Scope

## 15.1 MVP Must-Haves

- `sh1pt actions list`
- `sh1pt actions info <name>`
- `sh1pt actions plan <name>`
- `sh1pt actions install <name> --dry-run`
- `sh1pt actions install <name> --pr`
- `sh1pt actions audit`
- Local registry support
- One real action package: `vu1nz-scan`
- Manifest parser
- Diff preview
- Basic Git branch/commit support
- GitHub PR creation through `gh` CLI
- Basic security warnings

## 15.2 MVP Should-Haves

- `sh1pt skills list`
- `sh1pt skills retrieve <name>`
- `sh1pt skills install <name>`
- One skill package: `modern-web`
- JSON output mode
- Machine-readable audit results

## 15.3 MVP Nice-to-Haves

- sh1pt.com registry API
- User auth
- Private packages
- Pack installs
- GitHub App integration
- Web UI install flow

---

## 16. Success Metrics

## 16.1 Developer Adoption

- Number of CLI installs
- Number of action installs
- Number of PRs generated
- Number of repos connected
- Number of repeat users

## 16.2 Security Value

- Number of unsafe workflows detected
- Number of workflows converted from `@main` to pinned versions
- Number of excessive permissions warnings
- Number of `write-all` permissions removed

## 16.3 Business Metrics

- Free-to-paid conversion rate
- Number of connected GitHub orgs
- Number of private registry customers
- Number of agency accounts
- Monthly recurring revenue from workflow automation packs

---

## 17. Risks

## 17.1 Supply Chain Risk

If sh1pt allows arbitrary third-party packages to run scripts, it could become a supply-chain attack vector.

Mitigation:

- Declarative manifests only.
- No install scripts.
- Diff preview.
- PR-first installs.
- Trust levels.
- Signature support later.

## 17.2 GitHub Token Risk

If the CLI asks for broad GitHub tokens, users could accidentally grant dangerous access.

Mitigation:

- Prefer `gh` CLI auth initially.
- Request minimal scopes.
- Avoid storing tokens when possible.
- Document required scopes clearly.

## 17.3 Bad Workflow Templates

A trusted package could still accidentally introduce risky workflow behavior.

Mitigation:

- Built-in audit before install.
- Package review process.
- CI tests for package manifests.
- Permission linting.

## 17.4 User Trust

Developers are rightly suspicious of automation installers.

Mitigation:

- No `curl | bash` positioning.
- Show diffs.
- Show manifests.
- Use PRs.
- Use open-source registry.

---

## 18. Future Features

- Action package signing
- Publisher verification
- Private org registries
- GitHub App install mode
- Browser-based action store
- Automatic PRs for action updates
- Auto-hardening existing workflows
- Workflow permission minimizer
- Secret usage analyzer
- AI-generated workflow creation
- Framework-specific packs
- Client repo compliance dashboard
- sh1pt marketplace monetization
- Package ratings and reviews
- SBOM generation for GitHub workflows

---

## 19. Example Action Pack: Repo Security Baseline

```txt
repo-security-baseline
  - vu1nz-scan
  - dependency-review
  - secret-scan
  - codeql
  - scorecard
```

Install:

```bash
sh1pt packs install repo-security-baseline --pr
```

Expected output:

```txt
Pack: repo-security-baseline
Actions included:
  - vu1nz-scan
  - dependency-review
  - secret-scan
  - codeql
  - scorecard

Files to create:
  .github/workflows/vu1nz-scan.yml
  .github/workflows/dependency-review.yml
  .github/workflows/codeql.yml
  .github/workflows/scorecard.yml

Risk level:
  medium

Recommended install mode:
  pull request
```

---

## 20. Recommended Implementation Plan

## Phase 1: Local CLI MVP

- Create `packages/cli`
- Implement command router
- Implement local registry loader
- Add `actions list`
- Add `actions info`
- Add manifest validation
- Add `vu1nz-scan` package

## Phase 2: Plan + Diff

- Add install planner
- Add template renderer
- Add file conflict detection
- Add diff generation
- Add `actions plan`
- Add `actions install --dry-run`

## Phase 3: Git + PR Install

- Add git repo detection
- Add branch creation
- Add commit support
- Add GitHub PR creation through `gh`
- Add `actions install --pr`

## Phase 4: Audit

- Add workflow YAML scanner
- Detect unsafe permissions
- Detect unpinned actions
- Detect unsafe triggers
- Detect shell download patterns
- Add `actions audit`

## Phase 5: Skills

- Add skill manifest format
- Add `skills list`
- Add `skills retrieve`
- Add `skills install`
- Add `modern-web` sample skill

## Phase 6: sh1pt Cloud

- Add hosted registry endpoint
- Add GitHub OAuth/GitHub App connection
- Add web UI action store
- Add cloud PR creation
- Add paid private registries

---

## 21. Open Questions

- Should the public npm package be `sh1pt` or `@profullstack/sh1pt`?
- Should action packages live in the main sh1pt repo or a separate registry repo?
- Should community packages be accepted immediately or only after manual review?
- Should MVP require `gh` CLI, or should it use GitHub API directly?
- Should high-security mode pin all third-party actions to commit SHAs?
- Should sh1pt cloud use a GitHub App instead of OAuth tokens?
- Should package manifests support variables and prompts in MVP?

---

## 22. Final Recommendation

Build this.

It fits sh1pt extremely well because sh1pt is already about shipping automation, and GitHub Actions installation is a concrete, monetizable, developer-friendly wedge.

The important product decision is to be safer than the usual installer pattern.

Do not position sh1pt CLI as:

```bash
curl random-url | bash
```

Position it as:

```bash
sh1pt actions install vu1nz-scan --pr
```

That creates a clear difference:

- Other tools blindly execute automation.
- sh1pt proposes automation through reviewable pull requests.

That is the right foundation for both human developers and AI coding agents.


PRD: sh1pt CLI — Safe GitHub Actions + Agent Skills Installer #420

Description

PRD: sh1pt CLI — Safe GitHub Actions + Agent Skills Installer

1. Product Summary

2. Problem

3. Goals

Primary Goals

Secondary Goals

4. Non-Goals

5. Target Users

5.1 Solo Developers

5.2 Agencies

5.3 Open Source Maintainers

5.4 AI Coding Agent Users

5.5 sh1pt Cloud Users

6. Product Positioning

7. Core Concepts

7.1 Action Package

7.2 Skill Package

7.3 Registry

7.4 Install Plan

7.5 Reviewable Install

8. CLI Command Design

8.1 Global Commands

8.2 Repository Commands

8.3 Action Discovery

8.4 Action Planning

8.5 Action Installation

8.6 Action Updates

8.7 Action Audit

8.8 Skill Commands

8.9 Pack Commands

9. Example MVP Action Package

10. Security Requirements

10.1 No Arbitrary Install Scripts

10.2 Pull Request First

10.3 Diff Preview Required

10.4 Permission Minimization

10.5 Version Pinning

10.6 Secret Safety

10.7 Local Execution Safety

10.8 Trust Levels

11. Registry Design

11.1 Registry Structure

11.2 Registry Metadata

11.3 Registry Sources

12. Technical Architecture

12.1 Stack

12.2 Suggested Repo Layout

12.3 CLI Package

12.4 CLI Entry

13. GitHub Integration

13.1 MVP Options

13.2 PR Install Flow

13.3 PR Title

13.4 PR Body

14. sh1pt Cloud Integration

14.1 User Flow

14.2 Paid Features

15. MVP Scope

15.1 MVP Must-Haves

15.2 MVP Should-Haves

15.3 MVP Nice-to-Haves

16. Success Metrics

16.1 Developer Adoption

16.2 Security Value

16.3 Business Metrics

17. Risks

17.1 Supply Chain Risk

17.2 GitHub Token Risk

17.3 Bad Workflow Templates

17.4 User Trust

18. Future Features

19. Example Action Pack: Repo Security Baseline

20. Recommended Implementation Plan

Phase 1: Local CLI MVP

Phase 2: Plan + Diff

Phase 3: Git + PR Install

Phase 4: Audit

Phase 5: Skills