codeforerunner 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

codeforerunner/__init__.py

@@ -1 +1,6 @@
-__version__ = "0.2.0"
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("codeforerunner")
+except PackageNotFoundError:
+    __version__ = "0.0.0"  # running from source without install

codeforerunner/bundle.py

@@ -0,0 +1,58 @@
+"""Shared prompt resolution used by cli.py and mcp_server.py."""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _package_prompts() -> Path:
+    return Path(__file__).parent / "prompts"
+
+
+def find_prompts_root(repo_arg: str | Path | None = None) -> Path:
+    """Return the prompts root directory (parent of tasks/).
+
+    Resolution order:
+    1. {repo_arg}/prompts/ if given and contains tasks/
+    2. Walk up from cwd looking for prompts/tasks/ (checkout compat)
+    3. Package-bundled prompts (always available after pip install)
+    """
+    if repo_arg is not None:
+        p = Path(repo_arg) / "prompts"
+        if (p / "tasks").is_dir():
+            return p
+        raise FileNotFoundError(
+            f"no prompts/tasks/ found under {str(repo_arg)!r}"
+        )
+
+    here = Path.cwd().resolve()
+    for candidate in [here, *here.parents]:
+        if (candidate / "prompts" / "tasks").is_dir():
+            return candidate / "prompts"
+
+    pkg = _package_prompts()
+    if (pkg / "tasks").is_dir():
+        return pkg
+
+    raise FileNotFoundError(
+        "could not find prompts/tasks/; specify --repo or reinstall the package"
+    )
+
+
+def resolve_bundle(prompts_root: Path, task: str) -> str:
+    """Concatenate system/base.md + sorted partials/*.md + tasks/<task>.md."""
+    task_path = prompts_root / "tasks" / f"{task}.md"
+    if not task_path.is_file():
+        raise FileNotFoundError(f"unknown task {task!r} (no {task_path})")
+
+    parts: list[str] = []
+    base = prompts_root / "system" / "base.md"
+    if base.is_file():
+        parts.append(f"<!-- system: base.md -->\n{base.read_text(encoding='utf-8').rstrip()}")
+
+    partials_dir = prompts_root / "partials"
+    if partials_dir.is_dir():
+        for p in sorted(partials_dir.glob("*.md")):
+            parts.append(f"<!-- partial: {p.name} -->\n{p.read_text(encoding='utf-8').rstrip()}")
+
+    parts.append(f"<!-- task: {task_path.name} -->\n{task_path.read_text(encoding='utf-8').rstrip()}")
+    return "\n\n".join(parts) + "\n"

codeforerunner/cli.py

@@ -1,4 +1,4 @@
-"""Thin CLI orchestration. Product logic lives in `prompts/`. See SPEC.md §D.cli."""
+"""Thin CLI orchestration. Product logic lives in prompts/. See SPEC.md §D.cli."""
 
 from __future__ import annotations
 
@@ -8,36 +8,29 @@ import sys
 from pathlib import Path
 from typing import Sequence
 
+from codeforerunner.bundle import find_prompts_root, resolve_bundle
+
 SCAN_EXEMPT_TASKS = frozenset({"scan", "init-agent-onboarding"})
 SCAN_DONE_ENV = "FORERUNNER_SCAN_DONE"
 
 
-def _repo_root(start: Path | None = None) -> Path:
-    """Walk up from cwd (or `start`) to a directory containing `prompts/tasks`."""
-    here = (start or Path.cwd()).resolve()
-    for candidate in [here, *here.parents]:
-        if (candidate / "prompts" / "tasks").is_dir():
-            return candidate
-    raise FileNotFoundError(
-        "could not locate codeforerunner repo root (no prompts/tasks/ found upward)"
-    )
-
-
-def _read(path: Path) -> str:
-    return path.read_text(encoding="utf-8")
-
-
 def cmd_doc(args: argparse.Namespace) -> int:
-    """Resolve `prompts/system/base.md` + `prompts/partials/*.md` + `prompts/tasks/<task>.md` to stdout."""
-    root = _repo_root(Path(args.repo) if args.repo else None)
-    task_path = root / "prompts" / "tasks" / f"{args.task}.md"
+    """Resolve base + partials + task bundle to stdout."""
+    try:
+        prompts_root = find_prompts_root(args.repo)
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    task_path = prompts_root / "tasks" / f"{args.task}.md"
     if not task_path.is_file():
         print(f"error: unknown task '{args.task}' (no {task_path})", file=sys.stderr)
         return 2
 
+    repo_root = Path(args.repo) if args.repo else Path.cwd()
     if (
         args.task not in SCAN_EXEMPT_TASKS
-        and (root / "forerunner.config.yaml").is_file()
+        and (repo_root / "forerunner.config.yaml").is_file()
         and not os.environ.get(SCAN_DONE_ENV)
     ):
         print(
@@ -46,18 +39,11 @@ def cmd_doc(args: argparse.Namespace) -> int:
             file=sys.stderr,
         )
 
-    parts: list[str] = []
-    base = root / "prompts" / "system" / "base.md"
-    if base.is_file():
-        parts.append(f"<!-- system: base.md -->\n{_read(base).rstrip()}")
-
-    partials_dir = root / "prompts" / "partials"
-    if partials_dir.is_dir():
-        for p in sorted(partials_dir.glob("*.md")):
-            parts.append(f"<!-- partial: {p.name} -->\n{_read(p).rstrip()}")
-
-    parts.append(f"<!-- task: {task_path.name} -->\n{_read(task_path).rstrip()}")
-    sys.stdout.write("\n\n".join(parts) + "\n")
+    try:
+        sys.stdout.write(resolve_bundle(prompts_root, args.task))
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
     return 0
 
 
@@ -89,11 +75,8 @@ def cmd_scan(args: argparse.Namespace) -> int:
 
 
 def cmd_check(args: argparse.Namespace) -> int:
-    """Run check rules when `forerunner.config.yaml` present. Silent no-op otherwise."""
-    try:
-        root = _repo_root(Path(args.repo) if args.repo else None)
-    except FileNotFoundError:
-        root = Path.cwd()
+    """Run check rules when forerunner.config.yaml present. Silent no-op otherwise."""
+    root = Path(args.repo).resolve() if args.repo else Path.cwd()
     from codeforerunner import check as _check
     from codeforerunner.config import ConfigError, load_from_repo
     try:
@@ -112,8 +95,12 @@ def cmd_check(args: argparse.Namespace) -> int:
 
 def cmd_mcp_server(args: argparse.Namespace) -> int:
     from codeforerunner import mcp_server
-    root = _repo_root(Path(args.repo) if args.repo else None)
-    return mcp_server.serve(root)
+    try:
+        prompts_root = find_prompts_root(args.repo)
+    except FileNotFoundError as e:
+        print(f"mcp_server: {e}", file=sys.stderr)
+        return 2
+    return mcp_server.serve(prompts_root)
 
 
 def cmd_generate(args: argparse.Namespace) -> int:
@@ -121,8 +108,8 @@ def cmd_generate(args: argparse.Namespace) -> int:
     from codeforerunner import providers as _providers
     from codeforerunner.config import load_from_repo
 
-    root = _repo_root(Path(args.repo) if args.repo else None)
-    cfg = load_from_repo(root)
+    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")
     model = args.model or (cfg.model if cfg else None)
@@ -133,7 +120,6 @@ def cmd_generate(args: argparse.Namespace) -> int:
     import io as _io
     buf = _io.StringIO()
     ns = argparse.Namespace(repo=getattr(args, "repo", None), task=args.task)
-    # Temporarily redirect stdout to capture cmd_doc output.
     real_stdout = sys.stdout
     sys.stdout = buf
     try:
@@ -146,10 +132,7 @@ 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,
-        )
+        print(f"error: missing API key; set ${env_var}", file=sys.stderr)
         return 3
 
     try:
@@ -168,7 +151,7 @@ def cmd_generate(args: argparse.Namespace) -> int:
 
 def cmd_doctor(args: argparse.Namespace) -> int:
     from codeforerunner import doctor
-    root = _repo_root(Path(args.repo) if args.repo else None)
+    root = Path(args.repo).resolve() if args.repo else Path.cwd()
     findings = doctor.run(root)
     sys.stdout.write(doctor.format_report(findings) + "\n")
     return 1 if any(f.severity == "error" for f in findings) else 0
@@ -179,7 +162,7 @@ def build_parser() -> argparse.ArgumentParser:
         prog="forerunner",
         description="Prompt-first repo documentation tooling. Thin CLI; product logic in prompts/.",
     )
-    p.add_argument("--repo", help="path to repo root (defaults to cwd ancestor with prompts/tasks/)")
+    p.add_argument("--repo", default=argparse.SUPPRESS, help="path to repo root")
     from codeforerunner import __version__ as _version
     p.add_argument("--version", action="version", version=f"forerunner {_version}")
     sub = p.add_subparsers(dest="cmd", required=True, metavar="<cmd>")
@@ -209,6 +192,11 @@ def build_parser() -> argparse.ArgumentParser:
     s_check.set_defaults(func=cmd_check)
 
     s_mcp = sub.add_parser("mcp-server", help="serve prompt bundles as MCP tools over stdio")
+    s_mcp.add_argument(
+        "--repo",
+        default=argparse.SUPPRESS,
+        help="path containing prompts/tasks/ (default: package-bundled prompts)",
+    )
     s_mcp.set_defaults(func=cmd_mcp_server)
 
     s_doctor = sub.add_parser("doctor", help="health report: skill parity + marketplace + installed dests")
@@ -229,6 +217,8 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: Sequence[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
+    if not hasattr(args, "repo"):
+        args.repo = None
     return args.func(args)
 
 

codeforerunner/installer.py

@@ -291,9 +291,7 @@ def add_subparser(sub: argparse._SubParsersAction) -> None:
 
 
 def _cli_entry(args: argparse.Namespace) -> int:
-    from codeforerunner.cli import _repo_root  # local import to avoid cycle
-
-    root = _repo_root(Path(args.repo) if args.repo else None)
+    root = Path(args.repo).resolve() if args.repo else Path.cwd()
     return install(
         agent=args.agent,
         repo_root=root,

codeforerunner/mcp_server.py

@@ -10,54 +10,23 @@ import sys
 from pathlib import Path
 from typing import Any, Iterable
 
-PROTOCOL_VERSION = "2024-11-05"
-SERVER_NAME = "codeforerunner"
-SERVER_VERSION = "0.2.0"
-
-
-def _repo_root(start: Path | None = None) -> Path:
-    here = (start or Path.cwd()).resolve()
-    for candidate in [here, *here.parents]:
-        if (candidate / "prompts" / "tasks").is_dir():
-            return candidate
-    raise FileNotFoundError(
-        "could not locate codeforerunner repo root (no prompts/tasks/ found upward)"
-    )
-
-
-def _read(path: Path) -> str:
-    return path.read_text(encoding="utf-8")
+from codeforerunner import __version__ as _pkg_version
+from codeforerunner.bundle import find_prompts_root, resolve_bundle
 
-
-def resolve_bundle(repo: Path, task: str) -> str:
-    """Concatenate system/base.md + sorted partials/*.md + tasks/<task>.md with marker comments."""
-    task_path = repo / "prompts" / "tasks" / f"{task}.md"
-    if not task_path.is_file():
-        raise FileNotFoundError(f"unknown task '{task}' (no {task_path})")
-
-    parts: list[str] = []
-    base = repo / "prompts" / "system" / "base.md"
-    if base.is_file():
-        parts.append(f"<!-- system: base.md -->\n{_read(base).rstrip()}")
-
-    partials_dir = repo / "prompts" / "partials"
-    if partials_dir.is_dir():
-        for p in sorted(partials_dir.glob("*.md")):
-            parts.append(f"<!-- partial: {p.name} -->\n{_read(p).rstrip()}")
-
-    parts.append(f"<!-- task: {task_path.name} -->\n{_read(task_path).rstrip()}")
-    return "\n\n".join(parts) + "\n"
+PROTOCOL_VERSION = "2025-03-26"
+SERVER_NAME = "codeforerunner"
+SERVER_VERSION = _pkg_version
 
 
-def _list_tasks(repo: Path) -> list[Path]:
-    tasks_dir = repo / "prompts" / "tasks"
+def _list_tasks(prompts_root: Path) -> list[Path]:
+    tasks_dir = prompts_root / "tasks"
     if not tasks_dir.is_dir():
         return []
     return sorted(tasks_dir.glob("*.md"))
 
 
 def _description_for(task_path: Path) -> str:
-    """First non-empty markdown line, stripped of leading '#' chars and whitespace."""
+    """First non-empty markdown line, stripped of leading '#' and whitespace."""
     for raw in task_path.read_text(encoding="utf-8").splitlines():
         line = raw.strip()
         if not line:
@@ -66,14 +35,14 @@ def _description_for(task_path: Path) -> str:
     return task_path.stem
 
 
-def _tools(repo: Path) -> list[dict[str, Any]]:
+def _tools(prompts_root: Path) -> list[dict[str, Any]]:
     return [
         {
             "name": p.stem,
             "description": _description_for(p),
             "inputSchema": {"type": "object", "properties": {}, "required": []},
         }
-        for p in _list_tasks(repo)
+        for p in _list_tasks(prompts_root)
     ]
 
 
@@ -88,12 +57,11 @@ def _err(req_id: Any, code: int, message: str) -> dict[str, Any]:
 SCAN_EXEMPT_TOOLS = frozenset({"init-agent-onboarding", "scan"})
 
 
-def _handle(repo: Path, msg: dict[str, Any], state: dict[str, Any]) -> dict[str, Any] | None:
+def _handle(prompts_root: Path, msg: dict[str, Any], state: dict[str, Any]) -> dict[str, Any] | None:
     method = msg.get("method")
     req_id = msg.get("id")
     params = msg.get("params") or {}
 
-    # Notifications: no id, no response.
     if method == "notifications/initialized":
         return None
     if req_id is None and isinstance(method, str) and method.startswith("notifications/"):
@@ -110,11 +78,11 @@ def _handle(repo: Path, msg: dict[str, Any], state: dict[str, Any]) -> dict[str,
         )
 
     if method == "tools/list":
-        return _ok(req_id, {"tools": _tools(repo)})
+        return _ok(req_id, {"tools": _tools(prompts_root)})
 
     if method == "tools/call":
         name = params.get("name")
-        task_path = repo / "prompts" / "tasks" / f"{name}.md"
+        task_path = prompts_root / "tasks" / f"{name}.md"
         if not isinstance(name, str) or not task_path.is_file():
             return _err(req_id, -32602, f"unknown tool: {name!r}")
         if name not in SCAN_EXEMPT_TOOLS and not state.get("scan_called"):
@@ -126,7 +94,7 @@ def _handle(repo: Path, msg: dict[str, Any], state: dict[str, Any]) -> dict[str,
         if name == "scan":
             state["scan_called"] = True
         try:
-            text = resolve_bundle(repo, name)
+            text = resolve_bundle(prompts_root, name)
         except Exception as e:  # pragma: no cover - defensive
             return _err(req_id, -32603, f"internal error: {e}")
         return _ok(
@@ -137,7 +105,7 @@ def _handle(repo: Path, msg: dict[str, Any], state: dict[str, Any]) -> dict[str,
     return _err(req_id, -32601, f"method not found: {method!r}")
 
 
-def serve(repo: Path, stdin: Iterable[str] = sys.stdin, stdout=sys.stdout, stderr=sys.stderr) -> int:
+def serve(prompts_root: Path, stdin: Iterable[str] = sys.stdin, stdout=sys.stdout, stderr=sys.stderr) -> int:
     state: dict[str, Any] = {"scan_called": False}
     for raw in stdin:
         line = raw.strip()
@@ -153,7 +121,7 @@ def serve(repo: Path, stdin: Iterable[str] = sys.stdin, stdout=sys.stdout, stder
             continue
 
         try:
-            resp = _handle(repo, msg, state)
+            resp = _handle(prompts_root, msg, state)
         except Exception as e:  # pragma: no cover - defensive
             print(f"mcp_server: handler error: {e}", file=stderr)
             resp = _err(msg.get("id"), -32603, f"internal error: {e}")
@@ -166,11 +134,11 @@ def serve(repo: Path, stdin: Iterable[str] = sys.stdin, stdout=sys.stdout, stder
 
 def main(argv: list[str] | None = None) -> int:
     try:
-        repo = _repo_root()
+        prompts_root = find_prompts_root()
     except FileNotFoundError as e:
         print(f"mcp_server: {e}", file=sys.stderr)
         return 2
-    return serve(repo)
+    return serve(prompts_root)
 
 
 if __name__ == "__main__":

codeforerunner/prompts/partials/context-format.md

@@ -0,0 +1,29 @@
+# Context Format — Partial
+
+Context is passed as a single block immediately before the task prompt:
+
+<context>
+<repo_root>/path/to/repo</repo_root>
+
+<file_tree>
+.
+├── src/
+│   └── index.ts
+└── package.json
+</file_tree>
+
+<files>
+<file path="package.json">
+{ "name": "my-app" }
+</file>
+</files>
+</context>
+
+## Rules for Context Assembly
+
+1. File tree is always included — full tree respecting .gitignore and .forerunnerignore
+2. File contents are selective — include only files relevant to the current task
+3. File size limit — truncate at 300 lines; append <!-- truncated --> if cut
+4. Binary files — never include contents; list in tree only
+5. Secrets — never include .env files or credential files
+6. Order — config/manifest files first, then entry points, then supporting modules

codeforerunner/prompts/partials/output-rules.md

@@ -0,0 +1,39 @@
+# Output Rules — Partial
+
+## Markdown Standards
+- Use ATX-style headers (#, ##, ###) — never underline style
+- Fenced code blocks must always include a language identifier
+- Bold (**text**) for key terms on first use only
+- Tables must have header rows
+
+## File Output Format
+When writing to a specific file, the first line must be:
+<!-- output: path/to/output/file.md -->
+Followed immediately by the file content. No preamble.
+
+## Accuracy Rules
+- Never document a function, endpoint, or behavior not present in the provided code
+- Version numbers must come from lock files or manifests — never guess
+- Environment variables must come from .env.example or explicit code references
+
+## Diagram Rules (Mermaid)
+- All diagrams use Mermaid syntax in a fenced ```mermaid block
+- Node IDs: no spaces, no special characters except _ and -
+- Use graph TD for top-down, graph LR for left-right pipelines
+- Use sequenceDiagram for request/response flows
+- Use erDiagram for data models
+- Label all edges with action verbs
+- Max ~20 nodes per section diagram, ~40 for master
+
+## Length Guidelines
+| Document type           | Target length               |
+|-------------------------|-----------------------------|
+| README                  | 150-400 lines               |
+| API docs (per endpoint) | 20-60 lines                 |
+| Stack doc               | 100-300 lines               |
+| Master diagram          | 30-60 lines of Mermaid      |
+| Section diagram         | 10-25 lines of Mermaid      |
+| Flow doc                | 50-150 lines                |
+| Version audit           | scales with component count |
+| Check report            | 20-80 lines                 |
+| Review summary          | 10-30 lines                 |

codeforerunner/prompts/partials/stack-hints.md

@@ -0,0 +1,43 @@
+# Stack Detection Hints — Partial
+
+## Detection Signals
+
+### JavaScript / TypeScript
+- package.json, tsconfig.json, node_modules/
+- Frameworks: next.config.* -> Next.js, vite.config.* -> Vite, react in deps -> React
+
+### Python
+- pyproject.toml, setup.py, requirements.txt, Pipfile, uv.lock
+- Frameworks: fastapi -> FastAPI, flask -> Flask, django -> Django, airflow -> Airflow
+
+### Infrastructure / IaC
+- *.tf -> Terraform
+- .github/workflows/*.yml -> GitHub Actions
+- docker-compose.yml, Dockerfile -> Docker
+- kubernetes/, k8s/, *.yaml with kind: -> Kubernetes
+
+### ETL / Data Pipelines
+- dags/ -> Airflow
+- dbt_project.yml -> dbt
+- Prefect, Dagster, Luigi config files
+
+### Go
+- go.mod, go.sum; entry: main.go, cmd/
+
+### Rust
+- Cargo.toml, Cargo.lock; entry: src/main.rs, src/lib.rs
+
+## Documentation Style by Stack
+| Stack             | README style          | Diagram priority            | Key sections                           |
+|-------------------|-----------------------|-----------------------------|----------------------------------------|
+| React/Next.js     | User-facing + dev     | Component tree, routes      | Setup, env vars, routing, components   |
+| Python API        | Developer-first       | Endpoint flow, data model   | Install, endpoints, auth, models       |
+| Terraform module  | Ops-focused           | Infrastructure topology     | Inputs, outputs, resources, examples   |
+| ETL pipeline      | Data engineer-focused | Data flow, DAG structure    | Sources, transforms, targets, schedule |
+| CLI tool          | User-first            | Command flow                | Install, commands, flags, examples     |
+| Monorepo          | Package-first         | Package dependency graph    | Packages, shared libs, dev workflow    |
+
+## Monorepo Detection
+If the file tree contains multiple package.json, pyproject.toml, or equivalent manifest files
+at different directory levels, treat as a monorepo. Document each package independently
+and add a top-level dependency graph.

codeforerunner/prompts/system/base.md

@@ -0,0 +1,38 @@
+# codeforerunner — Base System Prompt
+
+## Role
+
+You are codeforerunner, an expert technical documentation agent. Your sole purpose is to analyze code repositories and produce accurate, well-structured, developer-friendly documentation.
+
+You are not a general assistant. You are focused exclusively on understanding codebases and producing documentation that is:
+- Accurate to what the code actually does — never hallucinate APIs, behavior, or integrations
+- Concise and scannable, not verbose
+- Consistently formatted using Markdown
+- Targeted at developers onboarding to this repo
+
+## Core Principles
+
+### 1. Ground Truth is the Code
+Always derive documentation from the provided file tree and file contents. If something is not evident from the provided context, say so explicitly — do not infer or invent.
+
+### 2. Be Stack-Aware
+Identify the technology stack, runtime, and ecosystem from the files provided. Adjust terminology, conventions, and documentation style to match the detected stack.
+
+### 3. Output is Always Markdown
+All outputs are valid Markdown. Use fenced code blocks with language identifiers. Use tables for comparisons. Use headers hierarchically.
+
+### 4. Never Pad
+Do not add motivational language, marketing copy, generic disclaimers, or filler sentences. Every sentence must carry information.
+
+### 5. Scope Boundaries
+Only document what is in scope for the current task.
+
+### 6. Acknowledge Gaps
+If context is insufficient, produce the best output possible and append a ## Gaps section.
+
+## Behavior Constraints
+- Do not ask clarifying questions mid-task unless explicitly instructed
+- Do not produce partial outputs with placeholder notes
+- Do not wrap output in meta-commentary
+- Begin your response with the documentation content directly
+- If a file path is specified as the output target, begin with: <!-- output: path/to/file.md -->

codeforerunner/prompts/tasks/api-docs.md

@@ -0,0 +1,47 @@
+# Task: Generate API Documentation
+
+Generates endpoint-level API documentation.
+Requires scan result. Best results when all route files are in context.
+
+## Input
+- Scan result
+- Route/handler files (all)
+- Auth middleware files
+- Request/response model/schema files
+
+## Per-Endpoint Format
+
+### `METHOD /path/to/endpoint`
+
+**Description:** What this endpoint does.
+**Auth:** Required / None / Optional
+
+**Request**
+| Field | Location | Type | Required | Description |
+|---|---|---|---|---|
+
+**Request Example**
+```http
+POST /api/users
+Authorization: Bearer <token>
+```
+
+**Response**
+| Status | Meaning |
+|---|---|
+| 200 | Success |
+| 401 | Unauthorized |
+
+**Response Example**
+```json
+{ "id": "uuid" }
+```
+
+## Rules
+- Document every endpoint, do not skip any
+- Group by resource/router
+- Include a summary table at the top: method, path, auth, one-line description
+- Claims must derive from provided files. Document every endpoint with available evidence; put unevidenced fields or unknown details in `## Gaps`.
+
+## Output
+<!-- output: docs/api.md -->

codeforerunner/prompts/tasks/audit.md

@@ -0,0 +1,44 @@
+# Task: Security and Dependency Audit
+
+Produces a structured security and dependency audit report for the repository.
+Requires scan result as input.
+
+## Input
+- Scan result
+- Manifest/lockfiles: package.json, package-lock.json, pyproject.toml, poetry.lock, go.mod, go.sum, Cargo.toml, Cargo.lock, requirements*.txt, Gemfile.lock
+- CI/CD workflow files
+- Dockerfile / compose files if present
+- .env.example or documented env vars
+
+## Instructions
+
+1. **Dependency inventory** — list all direct dependencies with pinned version (or "unpinned" if range only)
+2. **Known-vulnerable versions** — flag any dependency version with a published CVE you know of; note CVE ID and severity
+3. **Outdated pins** — flag dependencies pinned to versions that are end-of-life or significantly behind latest stable
+4. **Supply-chain risks** — flag: unpinned versions in CI (`uses: action@main`), `curl | bash` install patterns, unverified download steps
+5. **Secrets surface** — enumerate all env vars the repo reads; flag any that look like secrets hardcoded in non-.env files
+6. **Auth / input validation** — from entry-point and API handler files, flag: missing input sanitisation, direct string interpolation into shell commands or SQL, unauthenticated endpoints
+
+## Rules
+- Claims must derive from provided files. If evidence is absent, omit or document in `## Gaps`.
+- Do not fabricate CVE IDs. If you are not certain a CVE applies, note the concern without a CVE reference.
+- Severity: CRITICAL / HIGH / MEDIUM / LOW / INFO.
+- Only report findings with evidence; do not speculate.
+
+## Output Format
+
+```
+## Dependency Inventory
+| Package | Version | Pinned? |
+|---------|---------|---------|
+...
+
+## Findings
+### [SEVERITY] Title
+- **Evidence**: file:line or package@version
+- **Detail**: what the risk is
+- **Remediation**: concrete fix
+
+## Gaps
+- Items not assessable from provided files
+```