From 3e20e88aa669d3f36fb876307c3085db71d152ec Mon Sep 17 00:00:00 2001 From: "Derek Palmer (Creative)" Date: Tue, 12 May 2026 18:32:08 -0400 Subject: [PATCH 1/3] Add agent plugin distribution roadmap --- README.md | 8 ++ codeforerunner_spec.md => SPEC.md | 108 +++++++++++++++++++++ docs/agent-distribution-design.md | 155 ++++++++++++++++++++++++++++++ docs/plan.md | 32 ++++++ docs/requirements.md | 15 +++ docs/tasks.md | 11 +++ 6 files changed, 329 insertions(+) rename codeforerunner_spec.md => SPEC.md (81%) create mode 100644 docs/agent-distribution-design.md diff --git a/README.md b/README.md index c3197e5..fb92de7 100644 --- a/README.md +++ b/README.md @@ -194,6 +194,14 @@ enforcement: strict: true ``` +## Project spec and roadmap + +- `SPEC.md` is the canonical product specification. +- `docs/requirements.md` tracks user-facing requirements. +- `docs/plan.md` maps requirements to implementation phases. +- `docs/tasks.md` is the implementation checklist. +- `docs/agent-distribution-design.md` covers the planned Claude/Codex skill and plugin packaging. + ## Maintainer release flow Before the first public release, create the `codeforerunner` project on PyPI and configure a Trusted Publisher for: diff --git a/codeforerunner_spec.md b/SPEC.md similarity index 81% rename from codeforerunner_spec.md rename to SPEC.md index 3d27cc6..75de653 100644 --- a/codeforerunner_spec.md +++ b/SPEC.md @@ -56,6 +56,7 @@ Existing README guidance emphasizes clarity, concise structure, and keeping exam - Produce Mermaid diagrams that can live in version control alongside Markdown docs. - Document end-to-end integration and data flows across modules, services, jobs, queues, and external systems. - Let users plug codeforerunner into their preferred AI model stack instead of forcing one provider path or one API-key workflow. +- Install codeforerunner as an agent skill or plugin so users can invoke the repository documentation workflow directly from Claude Code, Codex, Gemini, or similar coding agents without manually finding prompt files. ## Scope @@ -234,6 +235,30 @@ The system should support at least these execution patterns: The project should avoid making user API key entry a core assumption of setup. If provider adapters support keys, they should be optional adapter details rather than the product's primary onboarding path. +### FR12 Agent skill and plugin distribution + +The system shall provide first-class agent installation artifacts so codeforerunner can be installed as a skill, plugin, or equivalent agent extension instead of requiring users to copy prompts or discover internal files manually. + +The distribution should include: +- canonical skill instructions that tell an agent how to run codeforerunner against a target repository, +- Codex plugin metadata and skill packaging, +- Claude plugin metadata and command or skill packaging where supported, +- shared source files for the canonical instructions so each agent package does not drift, +- an installer that detects supported agents and installs only the relevant artifacts, +- idempotent install and uninstall behavior, +- a clear fallback for unsupported agents that writes a portable Markdown skill file and setup instructions. + +The installer should be modeled after repos that ship a thin shell or PowerShell wrapper around a unified Node installer. The wrapper should be small, while the Node installer owns detection, file copying, marker-block updates, validation, and uninstall behavior. + +Initial supported agent targets should include: +- Codex skill/plugin package, +- Claude Code skill/plugin package, +- generic Markdown skill package for agents that support project or user-level instruction files. + +Future targets may include Gemini, Cursor, Windsurf, Cline, Copilot, OpenCode, or other agent hosts if their skill or rule-file conventions become stable enough to support. + +The agent-facing instructions should route work through the real CLI and repo-local config. They should not duplicate codeforerunner's full product spec. The skill should tell the agent how to inspect the target repo, choose safe commands, call `forerunner init`, `forerunner generate`, or `forerunner check`, and report changed docs back to the user. + ## Non-functional requirements ### NFR1 Developer experience @@ -269,6 +294,14 @@ The project should avoid making user API key entry a core assumption of setup. I - Secret files, environment files, and excluded paths must never be sent to an external model provider unless explicitly configured. - Local-first and provider-agnostic workflows should be treated as first-class design goals. +### NFR6 Agent package maintainability + +- Agent packages must derive from shared source instructions where practical. +- Generated package artifacts must be testable for file presence, metadata validity, and idempotent install behavior. +- Installers must avoid overwriting unrelated user content. +- Any injected global instruction blocks must use stable begin/end markers so uninstall can remove only codeforerunner-owned content. +- Agent-specific packages should stay thin and point back to the CLI, config, and docs rather than duplicating product behavior. + ## Licensing direction @@ -304,6 +337,8 @@ The final license text should be reviewed by counsel before public release, espe - Enforcement layer - Model adapter interface - CLI and config layer +- Agent skill/plugin packaging layer +- Cross-agent installer layer ### Architectural principle @@ -323,6 +358,71 @@ The same separation should apply to repository analysis. Technology-specific ana 8. Compare outputs against current files for drift detection. 9. Enforce review and update rules in hook or CI contexts. +### Agent distribution architecture + +The agent distribution should have one canonical source of truth and generated or copied package outputs: + +```text +agent/ + codeforerunner.skill.md + templates/ + codex-plugin.json + claude-plugin.json + generic-skill.md +bin/ + install-agent.js +install.sh +install.ps1 +plugins/ + codeforerunner/ + .codex-plugin/ + plugin.json + skills/ + codeforerunner/ + SKILL.md +.claude-plugin/ + plugin.json +skills/ + codeforerunner/ + SKILL.md +``` + +The exact paths may change once Codex and Claude package conventions are validated, but the ownership model should stay stable: +- `agent/codeforerunner.skill.md` is the canonical agent instruction source. +- `skills/codeforerunner/SKILL.md` is the generic skill artifact. +- `plugins/codeforerunner/.codex-plugin/plugin.json` is Codex plugin metadata. +- `.claude-plugin/plugin.json` is Claude plugin metadata if Claude plugin hooks are needed. +- `bin/install-agent.js` owns target detection, install, uninstall, and validation. +- `install.sh` and `install.ps1` are thin launchers only. + +Supported installer commands should include: + +```bash +forerunner agent install +forerunner agent install --only codex +forerunner agent install --only claude +forerunner agent uninstall +forerunner agent doctor +``` + +The direct shell install path may also be supported after packaging: + +```bash +curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash +``` + +The installer should: +- detect known agent config roots, +- copy codeforerunner-owned skill/plugin files, +- append marker-fenced instruction blocks only when an agent requires global injected context, +- avoid duplicate blocks on rerun, +- remove only marker-fenced or owned files on uninstall, +- print exact installed targets and skipped targets. + +The Codex package should prefer a plugin with a `skills/` directory and `plugin.json` interface metadata. The skill should trigger on repository documentation generation, README/API/diagram/flow documentation, stale-doc checks, and pre-commit or CI documentation enforcement setup. + +The Claude package should support either Claude's skill directory convention, Claude plugin metadata, or both, depending on current Claude Code capabilities. Any hooks should be limited to activation or command routing and must not silently run code generation against user repos. + ## Proposed outputs ### Repository files @@ -354,6 +454,10 @@ forerunner.config.yaml - `docs/flows/overview.md` - `docs/flows/.md` - `.codeforerunner/state.json` or similar metadata for generation checks +- `skills/codeforerunner/SKILL.md` +- `plugins/codeforerunner/.codex-plugin/plugin.json` +- `.claude-plugin/plugin.json` +- `install.sh`, `install.ps1`, and `bin/install-agent.js` ## CLI concept @@ -365,6 +469,9 @@ forerunner generate forerunner check forerunner review forerunner hook install +forerunner agent install +forerunner agent uninstall +forerunner agent doctor forerunner config init forerunner adapters list ``` @@ -471,6 +578,7 @@ An AI agent implementing this specification should work in this order: 10. Implement pre-commit hook installation and enforcement behavior. 11. Add tests using small fixture repositories, including at least one integration-heavy and one polyglot fixture. 12. Document analyzer limitations and unsupported constructs explicitly. +13. Add agent skill/plugin packaging after the core CLI contract is stable enough for agent instructions to call it without churn. This order matches `docs/plan.md`: the adapter **interface** belongs in Phase 0 foundations; a first **concrete adapter** and deeper fallback behavior land in a later phase after generators are exercising the interface. diff --git a/docs/agent-distribution-design.md b/docs/agent-distribution-design.md new file mode 100644 index 0000000..ba70ae4 --- /dev/null +++ b/docs/agent-distribution-design.md @@ -0,0 +1,155 @@ +# Agent Skill and Plugin Distribution Design + +## Goal + +Make codeforerunner installable as an agent skill or plugin so users can ask Claude Code, Codex, or another coding agent to run the documentation workflow without manually locating prompts or copying files. + +This is packaging and workflow glue around the real CLI. The agent package should not become a second implementation of codeforerunner. + +## Upstream Pattern + +The `caveman` repo uses three ideas worth mirroring: + +- one-line install entrypoints for macOS/Linux and Windows, +- thin shell/PowerShell wrappers around a unified Node installer, +- per-agent package folders such as Codex plugin metadata, Claude plugin metadata, generic skills, and command files. + +That shape keeps install UX simple while leaving agent-specific differences isolated. + +## Proposed Layout + +```text +agent/ + codeforerunner.skill.md + templates/ + codex-plugin.json + claude-plugin.json + generic-skill.md +bin/ + install-agent.js +install.sh +install.ps1 +plugins/ + codeforerunner/ + .codex-plugin/ + plugin.json + skills/ + codeforerunner/ + SKILL.md +.claude-plugin/ + plugin.json +skills/ + codeforerunner/ + SKILL.md +``` + +## Ownership Rules + +- `agent/codeforerunner.skill.md` is canonical. +- Generated or copied skill files must preserve canonical instruction content. +- Agent metadata files stay small and agent-specific. +- Installer owns only files below known codeforerunner package paths and marker-fenced blocks it creates. +- Uninstall removes only owned files/blocks. + +## Agent Instructions + +The skill should tell agents to: + +- inspect the target repo first, +- respect `forerunner.config.yaml`, include/exclude rules, and existing docs, +- prefer `forerunner check` for validation, +- use `forerunner init` for first setup, +- use `forerunner generate` for doc creation or refresh, +- report generated file changes and stale-doc failures clearly, +- avoid sending excluded or secret paths to external model providers, +- stop before destructive overwrites unless the CLI has an explicit managed-section strategy. + +The skill should avoid duplicating full product requirements. It should route to CLI behavior and repo-local config. + +## Installer Interface + +CLI commands: + +```bash +forerunner agent install +forerunner agent install --only codex +forerunner agent install --only claude +forerunner agent uninstall +forerunner agent doctor +``` + +One-line install after release: + +```bash +curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash +``` + +PowerShell equivalent: + +```powershell +irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex +``` + +## Installer Behavior + +Install: + +- detect known agent roots, +- copy owned skill/plugin artifacts, +- create parent directories as needed, +- append marker-fenced global instruction blocks only when required by a target agent, +- avoid duplicate blocks on rerun, +- print installed/skipped/failed targets. + +Uninstall: + +- remove owned skill/plugin files, +- remove marker-fenced blocks, +- leave unrelated user files untouched, +- print removed/skipped targets. + +Doctor: + +- check expected files exist, +- validate JSON metadata, +- verify canonical instruction hash or content match where practical, +- report stale copied artifacts. + +## Target Packages + +Codex: + +- package as `plugins/codeforerunner/`, +- include `.codex-plugin/plugin.json`, +- include `skills/codeforerunner/SKILL.md`, +- set plugin interface metadata for repository documentation, generated docs, diagrams, flow docs, and stale-doc checks. + +Claude Code: + +- support skill directory or `.claude-plugin/plugin.json`, depending on validated current convention, +- hooks may activate or expose commands, +- hooks must not silently generate docs against user repos. + +Generic: + +- ship `skills/codeforerunner/SKILL.md`, +- include manual setup notes for agents that support Markdown instructions but not package metadata. + +## Validation + +Tests should cover: + +- package file presence, +- plugin metadata parses as JSON, +- install creates expected files in temp agent roots, +- rerun is idempotent, +- uninstall removes only owned files and marker blocks, +- unsupported targets produce generic fallback guidance, +- `--only` limits touched targets. + +## Open Decisions + +- Whether `bin/install-agent.js` lives beside the Python CLI or is invoked only by shell wrappers. +- Whether `forerunner agent install` shells out to Node or uses Python for local installs. +- Which Claude package convention is current enough to support as first-class. +- Whether copied skill files are generated at build time or checked in as committed artifacts. diff --git a/docs/plan.md b/docs/plan.md index 7af3b12..bd8f2af 100644 --- a/docs/plan.md +++ b/docs/plan.md @@ -152,3 +152,35 @@ This plan breaks codeforerunner into small, independently shippable slices. Spec - **Priority:** Medium - **Covers:** Requirements 1 through 12 - Improve speed, logs, error messages, and partial-failure handling. + +## Phase 9: Agent skill and plugin distribution + +### Plan Item P9.1: Canonical agent instruction source +- **Priority:** High +- **Covers:** Requirement 15 +- Create one shared agent instruction source that explains how an AI coding agent should inspect a target repo, run codeforerunner commands, respect config/excludes, and report generated doc changes. + +### Plan Item P9.2: Codex plugin package +- **Priority:** High +- **Covers:** Requirement 15 +- Add Codex plugin metadata and a `skills/codeforerunner/SKILL.md` package generated from or copied from the canonical agent instruction source. + +### Plan Item P9.3: Claude skill or plugin package +- **Priority:** High +- **Covers:** Requirement 15 +- Add Claude-compatible skill or plugin metadata and instructions, with hooks limited to activation or command routing if hooks are needed. + +### Plan Item P9.4: Unified agent installer +- **Priority:** High +- **Covers:** Requirement 15 +- Add an idempotent installer that detects supported agents, installs owned skill/plugin files, supports `--only`, uninstall, and doctor checks, and prints installed/skipped targets. + +### Plan Item P9.5: Thin shell and PowerShell launchers +- **Priority:** Medium +- **Covers:** Requirement 15 +- Add `install.sh` and `install.ps1` wrappers that validate runtime prerequisites and delegate to the unified installer. + +### Plan Item P9.6: Installer and package tests +- **Priority:** Medium +- **Covers:** Requirement 15 +- Add tests for metadata validity, installed file layout, idempotent reruns, uninstall ownership, unsupported target reporting, and generic skill fallback. diff --git a/docs/requirements.md b/docs/requirements.md index 4923f1b..85e1862 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -171,3 +171,18 @@ As a developer, I want a generated runtime and EOL matrix so that I can quickly - WHEN `forerunner generate` runs, THEN the system SHALL query endoflife.date (or a compatible data source) for each detected runtime or platform and determine current support or EOL status. - WHEN runtimes are classified, THEN the system SHALL generate a `docs/versions.md` file containing tables for: currently EOL, approaching EOL, and in-support versions, including EOL or support end dates and links to where each version was found in the repo. +## Requirement 15: Agent skill and plugin distribution + +**User Story** + +As a developer using AI coding agents, I want to install codeforerunner as a skill or plugin so that my agent can run the documentation workflow without me finding prompt files manually. + +**Acceptance Criteria** + +- WHEN the repo is packaged, THEN it SHALL include canonical agent instructions for running codeforerunner against a target repository. +- WHEN Codex is supported, THEN the system SHALL provide Codex plugin metadata plus a skill directory that can be installed without manually copying prompts. +- WHEN Claude Code is supported, THEN the system SHALL provide Claude-compatible skill or plugin metadata and instructions. +- WHEN a user runs the installer, THEN it SHALL detect supported agent targets, install only relevant owned files, and report skipped targets clearly. +- WHEN the installer is rerun, THEN it SHALL avoid duplicate files or duplicate injected instruction blocks. +- WHEN uninstall runs, THEN it SHALL remove only codeforerunner-owned files or marker-fenced blocks. +- WHEN an agent target is unsupported, THEN the system SHALL provide a generic Markdown skill artifact and setup guidance. diff --git a/docs/tasks.md b/docs/tasks.md index c38bc92..680db9e 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -84,3 +84,14 @@ Prerequisite: **T0.9** is complete so AI-assisted generation in this phase uses - [ ] T8.4 Add the human-readable license summary to `README.md`. (Plan: P8.2, Requirement: 13) - [ ] T8.5 Improve performance and partial-failure handling. (Plan: P8.3, Requirements: 1 through 12) - [ ] T8.6 Improve logs, help text, and error messages for unsupported stacks or incomplete analysis. (Plan: P8.3, Requirements: 1 through 12) + +## Phase 9: Agent skill and plugin distribution + +- [ ] T9.1 Create the canonical agent instruction source for codeforerunner usage. (Plan: P9.1, Requirement: 15) +- [ ] T9.2 Add a generic `skills/codeforerunner/SKILL.md` artifact from the canonical instruction source. (Plan: P9.1, Requirement: 15) +- [ ] T9.3 Add Codex plugin metadata and package layout under `plugins/codeforerunner/`. (Plan: P9.2, Requirement: 15) +- [ ] T9.4 Add Claude-compatible skill or plugin metadata and package layout. (Plan: P9.3, Requirement: 15) +- [ ] T9.5 Implement `forerunner agent install`, `forerunner agent uninstall`, and `forerunner agent doctor`. (Plan: P9.4, Requirement: 15) +- [ ] T9.6 Add `--only ` support for scoped installs. (Plan: P9.4, Requirement: 15) +- [ ] T9.7 Add thin `install.sh` and `install.ps1` wrappers around the unified installer. (Plan: P9.5, Requirement: 15) +- [ ] T9.8 Add installer tests for metadata validity, idempotency, uninstall ownership, unsupported target reporting, and generic fallback output. (Plan: P9.6, Requirement: 15) From 0a901accfcd19115d765baadd3358c2afbb3c18c Mon Sep 17 00:00:00 2001 From: "Derek Palmer (Creative)" Date: Tue, 12 May 2026 21:53:20 -0400 Subject: [PATCH 2/3] Update agent distribution design and roadmap documentation - Clarified that standalone wrappers and one-line install commands are planned features and not currently runnable. - Updated the status of several roadmap items to reflect their completion, including Agent Config Exports and Human Docs, while adjusting the status of Thin Runtime Wrappers to planned. --- docs/agent-distribution-design.md | 6 +++--- docs/roadmap.md | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/agent-distribution-design.md b/docs/agent-distribution-design.md index 2a3a9e2..24ecfd5 100644 --- a/docs/agent-distribution-design.md +++ b/docs/agent-distribution-design.md @@ -79,20 +79,20 @@ forerunner agent uninstall forerunner agent doctor ``` -Before a CLI exists, install can be exposed through standalone wrappers: +Design example; standalone wrappers are planned and not currently runnable: ```bash bash install.sh --only codex pwsh ./install.ps1 --only claude ``` -One-line install after release: +Design example; one-line shell install is planned and not currently runnable: ```bash curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash ``` -PowerShell equivalent: +Design example; one-line PowerShell install is planned and not currently runnable: ```powershell irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex diff --git a/docs/roadmap.md b/docs/roadmap.md index e4ea486..7c920ac 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -4,7 +4,7 @@ Roadmap order follows `SPEC.md`. ## P0: Repo Truth Cleanup -Status: in progress. +Status: complete. - Replace stale v1 README claims. - Add compact spec for phased work. @@ -22,7 +22,7 @@ Status: planned. ## P2: Agent Config Exports -Status: in progress. +Status: complete. - Provide copyable instructions for common local agents. - Keep configs thin and prompt-referencing. @@ -30,7 +30,7 @@ Status: in progress. ## P3: Human Docs -Status: in progress. +Status: complete. - Explain manual prompt use. - Document prompt composition. @@ -50,7 +50,7 @@ Status: planned. ## P5: Thin Runtime Wrappers -Status: future. +Status: planned. Potential surfaces: From 1bbadc7220d2ac80bc7a79254dd2a59d683fb6ee Mon Sep 17 00:00:00 2001 From: "Derek Palmer (Creative)" Date: Tue, 12 May 2026 22:05:25 -0400 Subject: [PATCH 3/3] docs: clarify planned config and roadmap statuses --- docs/agent-distribution-design.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/agent-distribution-design.md b/docs/agent-distribution-design.md index 24ecfd5..f043972 100644 --- a/docs/agent-distribution-design.md +++ b/docs/agent-distribution-design.md @@ -60,11 +60,13 @@ The skill should tell agents to: - assemble repo context using `prompts/partials/context-format.md`, - run `prompts/tasks/scan.md` before downstream task prompts, - use task prompts from `prompts/tasks/` for README, API docs, stack docs, diagrams, flows, version audits, checks, and reviews, -- respect `forerunner.config.yaml.example` as proposed config shape only until a real loader exists, +- respect `forerunner.config.yaml` as the canonical config name, using the tracked example shape only until a real loader exists, - report generated file changes and stale-doc failures clearly, - avoid sending excluded or secret paths to external model providers, - stop before destructive overwrites unless the prompt output gives an explicit managed-section strategy. +Naming convention: repo/product `codeforerunner`; CLI/config `forerunner`; canonical config filename `forerunner.config.yaml`. + The skill should avoid duplicating full product requirements. It should route to the prompt pack and repo-local docs. ## Installer Interface