Skip to content

feat: multi-agent skill packaging — 30+ agent CLIs via caveman installer pattern #18

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
derek-palmer merged 2 commits into from
May 24, 2026
Merged

feat: multi-agent skill packaging — 30+ agent CLIs via caveman installer pattern #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
84fcc29
feat: multi-agent skill packaging — 12 slash commands + install.sh/ps1
derek-palmer May 24, 2026
7e904a1
feat: rewrite installers to match caveman's full agent-matrix pattern
derek-palmer May 24, 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
17 changes: 17 additions & 0 deletions .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
"name": "codeforerunner",
"description": "Repo documentation tooling for Claude Code. Adds /forerunner-scan, /forerunner-readme, /forerunner-check, and 9 other documentation slash commands.",
"owner": {
"name": "Derek Palmer",
"url": "https://github.com/derek-palmer"
},
"plugins": [
{
"name": "codeforerunner",
"description": "Model-agnostic repo documentation prompts. Slash commands for scan, readme, api-docs, diagrams, flows, stack-docs, version-audit, check, review, audit, changelog, and agent onboarding.",
"source": "./",
"category": "productivity"
}
]
}
5 changes: 5 additions & 0 deletions .codex/config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# codeforerunner Codex integration
# Skills installed here are available as Codex slash commands.

[features]
skills = true
48 changes: 48 additions & 0 deletions GEMINI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# codeforerunner — Gemini CLI context

Model-agnostic repository documentation tooling. Ships prompt packs for codebase analysis, doc generation, drift detection, and agent onboarding. Python CLI + MCP server + agent skills.

## Available tasks

Run any task via `forerunner doc <task>`, or use the installed Gemini extension skills:

| Slash command | Task | Description |
|---|---|---|
| `/forerunner-scan` | `scan` | Scan repo; always run first |
| `/forerunner-readme` | `readme` | Generate or refresh README.md |
| `/forerunner-api-docs` | `api-docs` | Generate API reference |
| `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |
| `/forerunner-flows` | `flows` | Document system flows |
| `/forerunner-stack-docs` | `stack-docs` | Stack-specific developer docs |
| `/forerunner-version-audit` | `version-audit` | Audit pinned versions vs EOL |
| `/forerunner-check` | `check` | Check docs for staleness |
| `/forerunner-review` | `review` | Doc-impact summary for PR review |
| `/forerunner-audit` | `audit` | Security and dependency audit |
| `/forerunner-changelog` | `changelog` | Generate changelog entry from git log |
| `/forerunner-init` | `init-agent-onboarding` | Bootstrap or refresh AGENTS.md |

## Workflow

1. Start with `/forerunner-scan` to collect repo evidence.
2. Run the documentation task you need.
3. Use `/forerunner-check` before commits to detect drift.

## CLI quick reference

```bash
forerunner doc <task> # Get composed prompt for a task
forerunner generate <task> # Call configured provider directly
forerunner check # Run drift-detection rules
forerunner doctor # Health report
forerunner install gemini # Install skills to Gemini config dir
```

## Config

Drop a `forerunner.config.yaml` at repo root to enable drift rules. Run `forerunner doctor --fix` to generate a starter config.

## Sources

- Prompts: `src/codeforerunner/prompts/tasks/`
- Skills: `skills/` (source) → `plugins/codeforerunner/skills/` (distribution)
- Repo: https://github.com/derek-palmer/codeforerunner
188 changes: 112 additions & 76 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,115 +2,160 @@

# codeForerunner

Model-agnostic repository documentation tooling. Ships a prompt pack for codebase analysis and doc generation, a thin Python CLI, an MCP server, a Codex marketplace plugin, and drift-detection rules that keep docs honest.
Model-agnostic repository documentation tooling. Ships a prompt pack for codebase analysis and doc generation, a thin Python CLI, an MCP server, drift-detection rules that keep docs honest — and native slash-command skills for Claude Code, Codex, Gemini CLI, and other agent CLIs.

## Install
## Two modes

### Mode A — Agent skill (recommended, no API key required)

Install forerunner's prompt pack as skills into your agent CLI. Each documentation task becomes a slash command (`/forerunner-readme`, `/forerunner-check`, etc.) available inside Claude Code, Codex, Gemini CLI, and other agents. Authentication is handled by your existing agent subscription — no separate API key needed.

```bash
# From a cloned repo
./install.sh

# One-liner (auto-detects Claude Code, Codex, Gemini CLI)
curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash

# Windows
irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex

# Via forerunner CLI (after pip install)
forerunner install --all claude
forerunner install --all codex
```

Then in your agent:

```
/forerunner-scan ← scan the repo first
/forerunner-readme ← generate README
/forerunner-check ← detect doc drift
```

### Mode B — Direct API (needs API key or Ollama)

Install the Python CLI and call your provider directly. Works without any agent CLI installed.

```bash
pipx install codeforerunner # recommended — isolated environment
pipx install codeforerunner # recommended
pip install codeforerunner # alternative
```

From source:
Configure a provider (or start Ollama for keyless local generation):

```bash
git clone https://github.com/derek-palmer/codeforerunner
cd codeforerunner
python -m pip install -e .
export ANTHROPIC_API_KEY=sk-...
forerunner generate readme --stream
```

Verify: `forerunner --help`
If no API key and no `--provider` flag, forerunner auto-detects Ollama at `localhost:11434` and falls back to local mode.

## Slash commands

| Command | Task | Purpose |
|---------|------|---------|
| `/forerunner-scan` | `scan` | Collect repo evidence (run first) |
| `/forerunner-readme` | `readme` | Generate or refresh README.md |
| `/forerunner-api-docs` | `api-docs` | Generate API reference docs |
| `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |
| `/forerunner-flows` | `flows` | Document system flows |
| `/forerunner-stack-docs` | `stack-docs` | Stack-specific developer docs |
| `/forerunner-version-audit` | `version-audit` | Audit pinned versions vs EOL |
| `/forerunner-check` | `check` | Check docs for staleness |
| `/forerunner-review` | `review` | Doc-impact summary for PR review |
| `/forerunner-audit` | `audit` | Security and dependency audit |
| `/forerunner-changelog` | `changelog` | Generate changelog from git log |
| `/forerunner-init` | `init-agent-onboarding` | Bootstrap or refresh AGENTS.md |

Slash command availability depends on the agent CLI. Claude Code, Codex, and Gemini CLI support all 12 commands after install.

## Skill install options

| Flag | Effect |
|------|--------|
| `./install.sh` | Auto-detect all agents, install all skills |
| `./install.sh --only claude` | Claude Code only |
| `./install.sh --only codex` | Codex only |
| `./install.sh --only gemini` | Gemini CLI only |
| `./install.sh --dry-run` | Preview, write nothing |
| `./install.sh --list` | Show detected agents + skill list |
| `./install.sh --uninstall` | Remove all installed skills |

## CLI

```bash
pip install codeforerunner
```

| Command | Purpose |
|---------|---------|
| `forerunner init` | Resolve agent-onboarding bundle to stdout (`--full` prepends scan; `--agents-only` is the default scope). |
| `forerunner init` | Resolve agent-onboarding bundle to stdout. |
| `forerunner scan` | Resolve scan bundle to stdout. |
| `forerunner doc <task>` | Resolve `base + partials + task` bundle to stdout. |
| `forerunner check` | Run drift-detection rules; silent no-op without `forerunner.config.yaml`. |
| `forerunner generate <task>` | Resolve bundle for `<task>` and call the configured provider. Add `--stream` to stream output token-by-token. |
| `forerunner doctor` | Single-screen health report: skill parity, marketplace validation, installed destinations, config, provider key. Add `--fix` to write a starter `forerunner.config.yaml` if absent. |
| `forerunner check` | Run drift-detection rules; no-op without `forerunner.config.yaml`. |
| `forerunner generate <task>` | Call configured provider directly. Add `--stream` for token-by-token output. Falls back to Ollama automatically when no API key is configured. |
| `forerunner doctor` | Health report: skill parity, config, provider key, local-mode status. Add `--fix` to write a starter config. |
| `forerunner mcp-server` | Serve prompt bundles as MCP tools over stdio (JSON-RPC 2.0). |
| `forerunner install <agent>` | Idempotently write the canonical skill into agent-specific directories. |
| `forerunner install <agent>` | Install canonical skill into agent-specific directory. Add `--all` for all per-task skills. |

## Prompt Pack
## Prompt pack

Prompts are bundled inside the package at `src/codeforerunner/prompts/`.

```text
prompts/
├── system/
│ └── base.md
├── system/base.md
├── partials/
│ ├── context-format.md
│ ├── output-rules.md
│ └── stack-hints.md
└── tasks/
├── scan.md
├── init-agent-onboarding.md
├── readme.md
├── api-docs.md
├── stack-docs.md
├── diagrams.md
├── flows.md
├── version-audit.md
├── check.md
├── review.md
├── audit.md
└── changelog.md
├── scan.md api-docs.md audit.md
├── readme.md diagrams.md changelog.md
├── check.md flows.md version-audit.md
├── review.md stack-docs.md
└── init-agent-onboarding.md
```

| Task | Purpose |
|------|---------|
| `scan` | Structured repo scan used by downstream tasks. |
| `init-agent-onboarding` | Generates or updates `AGENTS.md` from repo evidence. |
| `readme` | Generates or rewrites a top-level README. |
| `api-docs` | Documents public APIs. |
| `stack-docs` | Documents stack-specific areas. |
| `diagrams` | Generates Mermaid architecture or flow diagrams. |
| `flows` | Documents user, request, job, or data flows. |
| `version-audit` | Audits pinned versions from manifests, lockfiles, workflows, IaC. |
| `check` | Checks existing docs for staleness against a fresh scan. |
| `review` | Summarizes documentation impact for review. |
| `audit` | Security and dependency audit report. |
| `changelog` | Generates a Keep-a-Changelog entry from git log. |

## Quick Start
## Quick start (agent skill mode)

```bash
# 1. Point your agent at the scan prompt
forerunner scan
# Install skills into Claude Code
curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash

# 2. Generate or update docs for a task
export FORERUNNER_SCAN_DONE=1
forerunner doc readme

# 3. Direct model call (needs provider config)
forerunner generate readme --stream
# In Claude Code:
# /forerunner-scan → scans your repo
# /forerunner-readme → generates README.md
# /forerunner-check → checks for doc drift
```

## GitHub Action
## Quick start (direct API mode)

Use forerunner check as a reusable action in any workflow:
```bash
# 1. Install and configure
pip install codeforerunner
export ANTHROPIC_API_KEY=sk-...

```yaml
- uses: derek-palmer/codeforerunner@v0.3.2
# 2. Run a task
forerunner generate readme --stream

# 3. Enable drift detection
forerunner doctor --fix # writes forerunner.config.yaml
forerunner check # run any time or as pre-commit hook
```

With a pinned version:
## GitHub Action

```yaml
- uses: derek-palmer/codeforerunner@v0.3.2
with:
version: '0.3.2'
```

No-op when `forerunner.config.yaml` is absent.

## Configuration

Copy `forerunner.config.yaml.example` to `forerunner.config.yaml` to opt in. Without that file, `forerunner check` is a silent no-op. Generate a starter config with:
Copy `forerunner.config.yaml.example` to `forerunner.config.yaml` to opt in to drift rules. Generate a starter config with:

```bash
forerunner doctor --fix
Expand All @@ -122,7 +167,7 @@ forerunner doctor --fix
provider: anthropic # anthropic | openai | google | ollama
model: claude-opus-4-7
api_key_env:
anthropic: ANTHROPIC_API_KEY # override per-provider env var name
anthropic: ANTHROPIC_API_KEY

tasks:
check:
Expand All @@ -134,10 +179,10 @@ tasks:
- R5-no-python-package
- R7-no-mcp
- R8-no-marketplace
- RI1-missing-cli # inverse: doc claims CLI but file absent
- RI1-missing-cli
- RI5-missing-python-package
- RI7-missing-mcp
- RV1-version-drift # pinned version in docs ≠ pyproject.toml
- RV1-version-drift
ignore_paths:
- docs/legacy/**/*.md
```
Expand All @@ -159,15 +204,15 @@ tasks:
| `RI7-missing-mcp` | Doc references `forerunner mcp-server` but `mcp_server.py` absent |
| `RV1-version-drift` | Doc pins `codeforerunner==X.Y.Z` differing from current version |

### MCP Server
## MCP Server

`forerunner mcp-server` speaks JSON-RPC 2.0 over stdio and exposes one tool per `prompts/tasks/*.md`. A scan-first gate enforces SPEC V2: any tool except `scan` or `init-agent-onboarding` returns an error until `scan` has been called in the same session.

See `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.

## Providers

`forerunner generate` supports four providers. Set the appropriate env var before calling:
`forerunner generate` supports four providers. When no provider is explicitly configured and no API key is found, forerunner probes `localhost:11434` and falls back to Ollama automatically.

| Provider | Env var | Default model |
|----------|---------|---------------|
Expand All @@ -176,20 +221,11 @@ See `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.
| `google` | `GOOGLE_API_KEY` | `gemini-2.5-pro` |
| `ollama` | `OLLAMA_HOST` (optional) | `llama3` |

## Codex Plugin

```bash
forerunner install codex --marketplace
```

Installs the Codex marketplace entry and skill. Or install manually:
`forerunner install <agent>` copies the canonical skill into the agent-specific directory.

## Docs and Spec
## Docs and spec

- `SPEC.md` — canonical phase/task tracker
- `docs/getting-started.md` — manual prompt use
- `docs/prompt-guide.md` — how system, partial, and task prompts compose
- `docs/editor-agent-setup.md` — adapting prompts to local agents
- `docs/roadmap.md` — human-readable roadmap
- `docs/agent-distribution-design.md` — design backing Codex/Claude packages
- `docs/agent-distribution-design.md` — packaging and installer design
Loading
Loading