Update spec

AGENTS.md

@@ -4,15 +4,15 @@
 
 - This repo is in the `v2-overhaul` prompt-first transition; read `codeforerunner_v2_handoff.md` before trusting README claims.
 - Treat prompts as the core product: `prompts/system/base.md`, `prompts/partials/`, and `prompts/tasks/`.
-- `README.md`, `codeforerunner_spec.md`, `docs/`, and `agent-configs/` should stay aligned; update the spec when phase/task scope changes.
+- `README.md`, `SPEC.md`, `docs/`, and `agent-configs/` should stay aligned; update the spec when phase/task scope changes.
 - Do not reintroduce the old analyzer-heavy architecture unless explicitly requested.
 
 ## Current Sources Of Truth
 
 - `prompts/system/base.md` defines the base behavior and quality bar.
 - `prompts/tasks/scan.md` is the first task in every intended run; downstream task prompts expect its output.
 - `forerunner.config.yaml.example` is example config only; there is no implemented loader or CLI in this branch.
-- `codeforerunner_spec.md` tracks phased work via invariants and task rows; prefer status edits over broad rewrites.
+- `SPEC.md` tracks phased work via invariants and task rows; prefer status edits over broad rewrites.
 - There is no `src/`, tests, package manifest, Dockerfile, Makefile, hooks, or CI workflow in this branch.
 
 ## Work Direction
@@ -21,7 +21,7 @@
 - Do not claim working CLI, MCP, package publishing, Docker, pre-commit hooks, or CI unless corresponding files are actually added.
 - Use names consistently: repo/product `codeforerunner`, short CLI/config name `forerunner`, example config `forerunner.config.yaml`.
 - If adding legacy-style files such as `src/`, `tests/`, `Dockerfile`, `Makefile`, `pyproject.toml`, or `uv.lock`, make them directly support the prompt-first strategy.
-- Keep `docs/roadmap.md` and `codeforerunner_spec.md` honest about current vs future surfaces.
+- Keep `docs/roadmap.md` and `SPEC.md` honest about current vs future surfaces.
 
 ## Verification
 

README.md

@@ -60,11 +60,12 @@ prompts/
 
 ## Docs And Spec
 
-- `codeforerunner_spec.md` tracks phases, invariants, and tasks so future PRs can make small status updates instead of broad rewrites.
+- `SPEC.md` tracks phases, invariants, and tasks so future PRs can make small status updates instead of broad rewrites.
 - `docs/getting-started.md` explains manual prompt use.
 - `docs/prompt-guide.md` explains how system, partial, and task prompts compose.
 - `docs/editor-agent-setup.md` explains how to adapt prompts to local agents.
 - `docs/roadmap.md` separates current prompt assets from future wrappers.
+- `docs/agent-distribution-design.md` designs future Claude/Codex skill and plugin packaging.
 
 ## Configuration
 
@@ -80,6 +81,7 @@ Near-term work should keep the repo lightweight:
 | Todo | P1 | Prompt pack hardening: make task prompts consistent, composable, and evidence-first. |
 | Done | P2 | Agent config exports: Claude, Cursor, Copilot, Cline/Roo, and Windsurf scaffolds. |
 | Done | P3 | Human docs: getting started, prompt guide, editor setup, and roadmap. |
-| Later | P4 | Thin wrappers: CLI, MCP, hooks, and CI only after prompt contracts stabilize. |
+| Todo | P4 | Skill/plugin distribution: package prompt workflow for Claude/Codex setup. |
+| Later | P5 | Thin wrappers: CLI, MCP, hooks, and CI only after prompt contracts stabilize. |
 
-See `codeforerunner_spec.md` and `docs/roadmap.md` for the current phase plan.
+See `SPEC.md` and `docs/roadmap.md` for the current phase plan.

codeforerunner_spec.md → SPEC.md

@@ -12,13 +12,16 @@ C3: no claims for working CLI, MCP, hooks, CI, Docker, PyPI until files exist.
 C4: model/provider agnostic; provider-specific config optional.
 C5: docs must distinguish current state vs roadmap.
 C6: future legacy-style files (`src/`, `tests/`, `Dockerfile`, `Makefile`, `pyproject.toml`, `uv.lock`) must support prompt-first strategy directly.
+C7: skill/plugin packages ! route to prompt pack/current files until runtime wrappers exist.
 
 ## §I Interfaces
 
 I.prompts: `prompts/system/base.md` + `prompts/partials/*.md` + `prompts/tasks/*.md` → reusable prompt pack.
 I.config: `forerunner.config.yaml.example` → example config only; no loader yet.
 I.agent-configs: `agent-configs/*.md` → copyable editor-agent instructions.
 I.docs: `docs/*.md` → human setup, prompt guide, editor setup, roadmap.
+I.spec: `SPEC.md` → canonical phase/task tracker.
+I.future-skill-plugin: skill/plugin packages ? future surface; not implemented.
 I.future-cli: `forerunner` CLI ? future surface; not implemented.
 I.future-mcp: MCP server ? future surface; not implemented.
 I.future-hooks: pre-commit/CI checks ? future surface; not implemented.
@@ -32,6 +35,7 @@ V4: no doc says install/run `forerunner` until CLI exists.
 V5: no doc says Docker/Makefile/PyPI/CI/pre-commit exists until corresponding files exist.
 V6: spec ! updated when phases/tasks shift.
 V7: agent configs ! reference prompt files, not imaginary package install.
+V8: skill/plugin design ! avoid manual prompt discovery but must not claim installed package support before files exist.
 
 ## §P Phases
 
@@ -40,21 +44,27 @@ P0|x|repo truth cleanup|README/spec/AGENTS align with v2 state
 P1|.|prompt pack hardening|task prompts consistent, composable, evidence-first
 P2|x|agent config exports|editor-agent configs usable from tracked prompts
 P3|x|human docs|setup, prompt guide, editor setup, roadmap present
-P4|.|thin wrappers|CLI/MCP/hooks only after prompt contract stable
+P4|.|skill/plugin distribution design|simple agent setup planned without runtime claims
+P5|.|thin wrappers|CLI/MCP/hooks only after prompt contract stable
 
 ## §T Tasks
 
 id|status|phase|task|cites
 T1|x|P0|replace stale `README.md` with prompt-first current state|V1,V3,V4,V5
-T2|x|P0|add `codeforerunner_spec.md` phase/task tracker|V6
+T2|x|P0|move phase/task tracker to `SPEC.md`|V6,I.spec
 T3|x|P2|add `agent-configs/` scaffolds|V7,I.agent-configs
 T4|x|P3|add `docs/getting-started.md`|I.docs,V1
 T5|x|P3|add `docs/prompt-guide.md`|I.prompts,V2
 T6|x|P3|add `docs/editor-agent-setup.md`|I.agent-configs,V7
 T7|x|P3|add `docs/roadmap.md`|V3,I.future-cli,I.future-mcp,I.future-hooks
 T8|.|P1|review task prompts for shared input/output contracts|I.prompts,V2
-T9|.|P4|design CLI only after prompt workflow stabilizes|I.future-cli,C1
-T10|.|P4|design hooks/CI only after check/review prompts stabilize|I.future-hooks,C1
+T9|.|P5|design CLI only after prompt workflow stabilizes|I.future-cli,C1
+T10|.|P5|design hooks/CI only after check/review prompts stabilize|I.future-hooks,C1
+T11|x|P4|write skill/plugin distribution design|I.future-skill-plugin,V8
+T12|.|P4|add canonical skill source from prompt pack|I.prompts,I.future-skill-plugin,C7
+T13|.|P4|add Codex plugin package for prompt workflow|I.future-skill-plugin,V8
+T14|.|P4|add Claude skill/plugin package for prompt workflow|I.future-skill-plugin,V8
+T15|.|P4|add idempotent installer for owned agent artifacts|I.future-skill-plugin,V8
 
 ## §B Bugs
 

codeforerunner_v2_handoff.md

@@ -30,7 +30,7 @@ After the prompt-generation script runs, the repo should be moving toward this s
 codeforerunner/
 ├── LICENSE.md
 ├── README.md
-├── codeforerunner_spec.md
+├── SPEC.md
 ├── forerunner.config.yaml.example
 ├── prompts/
 │   ├── system/
@@ -79,7 +79,7 @@ Write a new `README.md` that:
 
 ### 2. Replace the spec
 
-Write a new `codeforerunner_spec.md` that:
+Write a new `SPEC.md` that:
 
 - Frames the product as prompt-first.
 - Defines prompt architecture first.
@@ -185,7 +185,7 @@ Each task prompt should define:
 
 1. Verify the prompt tree generated by the script is correct.
 2. Write the new `README.md`.
-3. Write the new `codeforerunner_spec.md`.
+3. Write the new `SPEC.md`.
 4. Create `agent-configs/` scaffolds.
 5. Create `docs/` scaffolds and fill first-pass content.
 6. Do a cleanup pass for stray legacy files and mismatched language in docs.

docs/agent-distribution-design.md

@@ -0,0 +1,165 @@
+# 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 tracked prompt pack. 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,
+- use `prompts/system/base.md` as the governing instruction source,
+- 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` 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
+
+Future CLI commands, once thin wrappers exist:
+
+```bash
+forerunner agent install
+forerunner agent install --only codex
+forerunner agent install --only claude
+forerunner agent uninstall
+forerunner agent doctor
+```
+
+Design example; standalone wrappers are planned and not currently runnable:
+
+```bash
+bash install.sh --only codex
+pwsh ./install.ps1 --only claude
+```
+
+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
+```
+
+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
+```
+
+## 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` is the first implementation or waits until package layout stabilizes.
+- Whether future `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.

docs/editor-agent-setup.md

@@ -30,5 +30,5 @@ Use `agent-configs/` as copyable starting points for editor-agent instructions.
 
 When prompt contracts change, update both:
 
-- `codeforerunner_spec.md`
+- `SPEC.md`
 - affected files in `agent-configs/`

docs/getting-started.md

@@ -37,4 +37,4 @@ base.md + context-format.md + target repo context + scan.md
 
 - Prompt composition: `docs/prompt-guide.md`
 - Editor setup: `docs/editor-agent-setup.md`
-- Phase tracker: `codeforerunner_spec.md`
+- Phase tracker: `SPEC.md`

docs/roadmap.md

@@ -1,10 +1,10 @@
 # Roadmap
 
-Roadmap order follows `codeforerunner_spec.md`.
+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,24 +22,35 @@ Status: planned.
 
 ## P2: Agent Config Exports
 
-Status: in progress.
+Status: complete.
 
 - Provide copyable instructions for common local agents.
 - Keep configs thin and prompt-referencing.
 - Avoid provider-specific assumptions.
 
 ## P3: Human Docs
 
-Status: in progress.
+Status: complete.
 
 - Explain manual prompt use.
 - Document prompt composition.
 - Document editor-agent setup.
 - Keep roadmap honest about current vs future surfaces.
 
-## P4: Thin Runtime Wrappers
+## P4: Skill/Plugin Distribution
 
-Status: future.
+Status: planned.
+
+- Add a canonical skill source derived from the prompt pack.
+- Add Codex plugin packaging for the prompt workflow.
+- Add Claude skill/plugin packaging for the prompt workflow.
+- Add an idempotent installer for owned agent artifacts.
+- Keep packages thin: they should route agents to tracked prompts and docs, not duplicate product logic.
+- Do not claim package install support until files exist.
+
+## P5: Thin Runtime Wrappers
+
+Status: planned.
 
 Potential surfaces: