codeforerunner 0.3.2__tar.gz → 0.4.0__tar.gz

codeforerunner-0.4.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: codeforerunner
+Version: 0.4.0
+Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
+Author: Derek Palmer
+License-Expression: LicenseRef-Codeforerunner-SAL-0.1
+Project-URL: Repository, https://github.com/derek-palmer/codeforerunner
+Project-URL: Issues, https://github.com/derek-palmer/codeforerunner/issues
+Keywords: repository-documentation,developer-tools,agent-tooling,code-generation,prompt-engineering,mcp,llm,documentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+![codeForerunner — your codebase gets a Forerunner; your docs finally see the light](images/readme_banner.png)
+
+# codeForerunner
+
+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.
+
+## 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
+pip install codeforerunner    # alternative
+```
+
+Configure a provider (or start Ollama for keyless local generation):
+
+```bash
+export ANTHROPIC_API_KEY=sk-...
+forerunner generate readme --stream
+```
+
+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. |
+| `forerunner scan` | Resolve scan bundle to stdout. |
+| `forerunner doc <task>` | Resolve `base + partials + task` bundle to stdout. |
+| `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>` | Install canonical skill into agent-specific directory. Add `--all` for all per-task skills. |
+
+## Prompt pack
+
+Prompts are bundled inside the package at `src/codeforerunner/prompts/`.
+
+```text
+prompts/
+├── system/base.md
+├── partials/
+│   ├── context-format.md
+│   ├── output-rules.md
+│   └── stack-hints.md
+└── tasks/
+    ├── 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
+```
+
+## Quick start (agent skill mode)
+
+```bash
+# Install skills into Claude Code
+curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
+
+# In Claude Code:
+# /forerunner-scan    → scans your repo
+# /forerunner-readme  → generates README.md
+# /forerunner-check   → checks for doc drift
+```
+
+## Quick start (direct API mode)
+
+```bash
+# 1. Install and configure
+pip install codeforerunner
+export ANTHROPIC_API_KEY=sk-...
+
+# 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
+```
+
+## GitHub Action
+
+```yaml
+- uses: derek-palmer/codeforerunner@v0.3.2
+```
+
+No-op when `forerunner.config.yaml` is absent.
+
+## Configuration
+
+Copy `forerunner.config.yaml.example` to `forerunner.config.yaml` to opt in to drift rules. Generate a starter config with:
+
+```bash
+forerunner doctor --fix
+```
+
+### Config fields
+
+```yaml
+provider: anthropic          # anthropic | openai | google | ollama
+model: claude-opus-4-7
+api_key_env:
+  anthropic: ANTHROPIC_API_KEY
+
+tasks:
+  check:
+    enabled_rules:
+      - R1-no-cli
+      - R2-no-pre-commit
+      - R3-no-ci
+      - R4-no-installer
+      - R5-no-python-package
+      - R7-no-mcp
+      - R8-no-marketplace
+      - RI1-missing-cli
+      - RI5-missing-python-package
+      - RI7-missing-mcp
+      - RV1-version-drift
+    ignore_paths:
+      - docs/legacy/**/*.md
+```
+
+### Drift rules
+
+| Rule | Fires when |
+|------|-----------|
+| `R1-no-cli` | Doc denies having a CLI, but `cli.py` is present |
+| `R2-no-pre-commit` | Doc denies having pre-commit hooks, but `.pre-commit-hooks.yaml` present |
+| `R3-no-ci` | Doc denies having CI, but `.github/workflows/*.yml` present |
+| `R4-no-installer` | Doc denies having an installer, but `installer.py` present |
+| `R5-no-python-package` | Doc denies having a Python package, but `pyproject.toml` present |
+| `R6-no-docker` | Doc denies having Docker, but `Dockerfile`/`compose.yml` present |
+| `R7-no-mcp` | Doc denies having an MCP server, but `mcp_server.py` present |
+| `R8-no-marketplace` | Doc denies having a marketplace, but `marketplace.json` present |
+| `RI1-missing-cli` | Doc references `forerunner` subcommands but `cli.py` absent |
+| `RI5-missing-python-package` | Doc shows `pip install codeforerunner` but `pyproject.toml` absent |
+| `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
+
+`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. 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 |
+|----------|---------|---------------|
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-opus-4-7` |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o` |
+| `google` | `GOOGLE_API_KEY` | `gemini-2.5-pro` |
+| `ollama` | `OLLAMA_HOST` (optional) | `llama3` |
+
+## 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` — packaging and installer design

codeforerunner-0.4.0/README.md

@@ -0,0 +1,231 @@
+![codeForerunner — your codebase gets a Forerunner; your docs finally see the light](images/readme_banner.png)
+
+# codeForerunner
+
+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.
+
+## 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
+pip install codeforerunner    # alternative
+```
+
+Configure a provider (or start Ollama for keyless local generation):
+
+```bash
+export ANTHROPIC_API_KEY=sk-...
+forerunner generate readme --stream
+```
+
+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. |
+| `forerunner scan` | Resolve scan bundle to stdout. |
+| `forerunner doc <task>` | Resolve `base + partials + task` bundle to stdout. |
+| `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>` | Install canonical skill into agent-specific directory. Add `--all` for all per-task skills. |
+
+## Prompt pack
+
+Prompts are bundled inside the package at `src/codeforerunner/prompts/`.
+
+```text
+prompts/
+├── system/base.md
+├── partials/
+│   ├── context-format.md
+│   ├── output-rules.md
+│   └── stack-hints.md
+└── tasks/
+    ├── 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
+```
+
+## Quick start (agent skill mode)
+
+```bash
+# Install skills into Claude Code
+curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
+
+# In Claude Code:
+# /forerunner-scan    → scans your repo
+# /forerunner-readme  → generates README.md
+# /forerunner-check   → checks for doc drift
+```
+
+## Quick start (direct API mode)
+
+```bash
+# 1. Install and configure
+pip install codeforerunner
+export ANTHROPIC_API_KEY=sk-...
+
+# 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
+```
+
+## GitHub Action
+
+```yaml
+- uses: derek-palmer/codeforerunner@v0.3.2
+```
+
+No-op when `forerunner.config.yaml` is absent.
+
+## Configuration
+
+Copy `forerunner.config.yaml.example` to `forerunner.config.yaml` to opt in to drift rules. Generate a starter config with:
+
+```bash
+forerunner doctor --fix
+```
+
+### Config fields
+
+```yaml
+provider: anthropic          # anthropic | openai | google | ollama
+model: claude-opus-4-7
+api_key_env:
+  anthropic: ANTHROPIC_API_KEY
+
+tasks:
+  check:
+    enabled_rules:
+      - R1-no-cli
+      - R2-no-pre-commit
+      - R3-no-ci
+      - R4-no-installer
+      - R5-no-python-package
+      - R7-no-mcp
+      - R8-no-marketplace
+      - RI1-missing-cli
+      - RI5-missing-python-package
+      - RI7-missing-mcp
+      - RV1-version-drift
+    ignore_paths:
+      - docs/legacy/**/*.md
+```
+
+### Drift rules
+
+| Rule | Fires when |
+|------|-----------|
+| `R1-no-cli` | Doc denies having a CLI, but `cli.py` is present |
+| `R2-no-pre-commit` | Doc denies having pre-commit hooks, but `.pre-commit-hooks.yaml` present |
+| `R3-no-ci` | Doc denies having CI, but `.github/workflows/*.yml` present |
+| `R4-no-installer` | Doc denies having an installer, but `installer.py` present |
+| `R5-no-python-package` | Doc denies having a Python package, but `pyproject.toml` present |
+| `R6-no-docker` | Doc denies having Docker, but `Dockerfile`/`compose.yml` present |
+| `R7-no-mcp` | Doc denies having an MCP server, but `mcp_server.py` present |
+| `R8-no-marketplace` | Doc denies having a marketplace, but `marketplace.json` present |
+| `RI1-missing-cli` | Doc references `forerunner` subcommands but `cli.py` absent |
+| `RI5-missing-python-package` | Doc shows `pip install codeforerunner` but `pyproject.toml` absent |
+| `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
+
+`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. 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 |
+|----------|---------|---------------|
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-opus-4-7` |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o` |
+| `google` | `GOOGLE_API_KEY` | `gemini-2.5-pro` |
+| `ollama` | `OLLAMA_HOST` (optional) | `llama3` |
+
+## 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` — packaging and installer design

{codeforerunner-0.3.2 → codeforerunner-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeforerunner"
-version = "0.3.2"
+version = "0.4.0"
 description = "Model-agnostic repository documentation tooling (prompt-first; thin CLI)."
 readme = "README.md"
 requires-python = ">=3.11"

{codeforerunner-0.3.2 → codeforerunner-0.4.0}/src/codeforerunner/cli.py

@@ -111,7 +111,8 @@ def cmd_generate(args: argparse.Namespace) -> int:
     repo_root = Path(args.repo).resolve() if args.repo else Path.cwd()
     cfg = load_from_repo(repo_root)
 
-    provider_name = args.provider or (cfg.provider if cfg else "anthropic")
+    explicit_provider = args.provider or (cfg.provider if cfg else None)
+    provider_name = explicit_provider or "anthropic"
     model = args.model or (cfg.model if cfg else None)
     provider_cls = _providers.get(provider_name)
     provider = provider_cls()
@@ -132,8 +133,19 @@ def cmd_generate(args: argparse.Namespace) -> int:
     env_var = (cfg.api_key_env.get(provider_name) if cfg else None) or provider.default_env_var
     api_key = os.environ.get(env_var)
     if api_key is None and provider_name != "ollama":
-        print(f"error: missing API key; set ${env_var}", file=sys.stderr)
-        return 3
+        if explicit_provider is None and _providers.ollama_available():
+            provider_name = "ollama"
+            provider_cls = _providers.get("ollama")
+            provider = provider_cls()
+            if not args.model:
+                model = provider.default_model
+            print("info: no API key; falling back to Ollama (local mode)", file=sys.stderr)
+        else:
+            msg = f"error: missing API key; set ${env_var}"
+            if explicit_provider is None:
+                msg += "\nhint: start Ollama for keyless local generation (https://ollama.com)"
+            print(msg, file=sys.stderr)
+            return 3
 
     if getattr(args, "stream", False):
         try:

{codeforerunner-0.3.2 → codeforerunner-0.4.0}/src/codeforerunner/doctor.py

@@ -225,13 +225,23 @@ def _check_config_loadable(repo: Path) -> list[Finding]:
 
 
 def _check_provider_api_key(repo: Path) -> list[Finding]:
+    from codeforerunner.providers.ollama import is_available as _ollama_available
+
     cfg_path = repo / CONFIG_FILENAME
     if not cfg_path.is_file():
+        if _ollama_available():
+            return [
+                Finding(
+                    "ok",
+                    "provider-api-key",
+                    "no config; Ollama running — generate will use local mode automatically",
+                )
+            ]
         return [
             Finding(
                 "ok",
                 "provider-api-key",
-                f"no {CONFIG_FILENAME}; provider key not checked",
+                f"no {CONFIG_FILENAME}; set an API key in config or start Ollama for keyless local generation",
             )
         ]
     try:
@@ -259,7 +269,7 @@ def _check_provider_api_key(repo: Path) -> list[Finding]:
             Finding(
                 "ok",
                 "provider-api-key",
-                "ollama needs no API key (OLLAMA_HOST optional)",
+                "running in local mode (Ollama; no API key needed)",
             )
         ]
     env_var = cfg.api_key_env.get(provider) or _DEFAULT_PROVIDER_ENV.get(provider, "")

{codeforerunner-0.3.2 → codeforerunner-0.4.0}/src/codeforerunner/installer.py

@@ -21,6 +21,23 @@ EXIT_USAGE = 2
 EXIT_BODY_MISMATCH = 3
 EXIT_UNMANAGED_DEST = 4
 
+# Per-task skill slugs (source: skills/<slug>/SKILL.md → plugins/codeforerunner/skills/<slug>/SKILL.md)
+TASK_SKILL_SLUGS: tuple[str, ...] = (
+    "codeforerunner",
+    "forerunner-scan",
+    "forerunner-readme",
+    "forerunner-api-docs",
+    "forerunner-audit",
+    "forerunner-changelog",
+    "forerunner-check",
+    "forerunner-diagrams",
+    "forerunner-flows",
+    "forerunner-init",
+    "forerunner-review",
+    "forerunner-stack-docs",
+    "forerunner-version-audit",
+)
+
 
 @dataclass(frozen=True)
 class Target:
@@ -44,9 +61,65 @@ def resolve_target(agent: str, override: Path | None) -> Target:
         return Target(agent, home / ".codex/skills/codeforerunner/SKILL.md")
     if agent == "claude":
         return Target(agent, home / ".claude/plugins/codeforerunner/skills/codeforerunner/SKILL.md")
+    if agent == "gemini":
+        raise ValueError(
+            "gemini install is handled via `gemini extensions install`; "
+            "run `./install.sh --only gemini` instead"
+        )
     raise ValueError(f"unknown agent '{agent}' (expected: codex, claude, generic)")
 
 
+def resolve_skill_target(agent: str, slug: str) -> Target:
+    """Return install target for a per-task skill slug."""
+    home = _home()
+    if agent == "codex":
+        return Target(agent, home / f".codex/skills/{slug}/SKILL.md")
+    if agent == "claude":
+        return Target(agent, home / f".claude/plugins/codeforerunner/skills/{slug}/SKILL.md")
+    raise ValueError(f"install_all not supported for agent '{agent}' (expected: codex, claude)")
+
+
+def install_all_skills(
+    *,
+    agent: str,
+    repo_root: Path,
+    check_only: bool,
+    out=None,
+    err=None,
+) -> int:
+    """Install all per-task skills for the given agent. Returns 0 on full success."""
+    out = out or sys.stdout
+    err = err or sys.stderr
+    any_error = False
+    for slug in TASK_SKILL_SLUGS:
+        src_path = repo_root / "plugins" / "codeforerunner" / "skills" / slug / "SKILL.md"
+        if not src_path.is_file():
+            print(f"warning: skill source not found: {src_path}", file=err)
+            continue
+        try:
+            target = resolve_skill_target(agent, slug)
+        except ValueError as e:
+            print(f"error: {e}", file=err)
+            return EXIT_USAGE
+        # For per-task skills use simple copy (no body-parity check against canonical)
+        dest = target.path
+        prefix = "would " if check_only else ""
+        if dest.exists():
+            src_trimmed = src_path.read_bytes().rstrip()
+            dest_trimmed = dest.read_bytes().rstrip()
+            if src_trimmed == dest_trimmed:
+                print(f"skip: {dest} (up-to-date)", file=out)
+                continue
+            action = "update"
+        else:
+            action = "create"
+        print(f"{prefix}{action}: {dest}", file=out)
+        if not check_only:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(src_path.read_bytes())
+    return EXIT_OK if not any_error else EXIT_BODY_MISMATCH
+
+
 def resolve_marketplace_target(agent: str, override: Path | None) -> Target:
     if agent == "generic":
         if override is None:
@@ -277,8 +350,11 @@ def install(
 
 
 def add_subparser(sub: argparse._SubParsersAction) -> None:
-    p = sub.add_parser("install", help="install skill into agent-specific directory (D.installer)")
-    p.add_argument("agent", choices=["codex", "claude", "generic"])
+    p = sub.add_parser("install", help="install skill(s) into agent-specific directories (D.installer)")
+    p.add_argument("agent", choices=["codex", "claude", "generic"], nargs="?",
+                   help="target agent (omit with --all to install to all detected agents)")
+    p.add_argument("--all", action="store_true",
+                   help="install all per-task skills for the specified agent")
     p.add_argument("--check", action="store_true", help="dry-run: print plan, write nothing")
     p.add_argument("--path", type=Path, help="dest path override (required for generic)")
     p.add_argument("--source", type=Path, help="source skill file (default: agent/codeforerunner.skill.md)")
@@ -292,6 +368,19 @@ def add_subparser(sub: argparse._SubParsersAction) -> None:
 
 def _cli_entry(args: argparse.Namespace) -> int:
     root = Path(args.repo).resolve() if args.repo else Path.cwd()
+
+    if getattr(args, "all", False):
+        agent = args.agent or "claude"
+        return install_all_skills(
+            agent=agent,
+            repo_root=root,
+            check_only=args.check,
+        )
+
+    if not args.agent:
+        print("error: specify an agent or use --all", file=sys.stderr)
+        return EXIT_USAGE
+
     return install(
         agent=args.agent,
         repo_root=root,