codeforerunner 0.4.4__tar.gz → 0.4.5__tar.gz

{codeforerunner-0.4.4/src/codeforerunner.egg-info → codeforerunner-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforerunner
-Version: 0.4.4
+Version: 0.4.5
 Summary: Model-agnostic repository documentation tooling (prompt-first; thin CLI).
 Author: Derek Palmer
 License-Expression: LicenseRef-Codeforerunner-SAL-0.1
@@ -29,7 +29,7 @@ Dynamic: license-file
 
 # codeForerunner
 
-[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)
+[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.5)](https://socket.dev/npm/package/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.
 
@@ -44,10 +44,15 @@ Install forerunner's prompt pack as skills into your agent CLI. Each documentati
 # One-liner (auto-detects Claude Code, Codex, Gemini CLI)
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# npm
+npx -y codeforerunner
+npm install -g codeforerunner
+
 # Windows
 irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex
 
-# Via forerunner CLI (after pip install)
+# Via Python CLI
+pip install codeforerunner
 forerunner install --all claude
 forerunner install --all codex
 ```
@@ -70,6 +75,7 @@ Then in your agent:
 | `/forerunner-api-docs` | `api-docs` | Generate API reference docs |
 | `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |
 | `/forerunner-flows` | `flows` | Document system flows |
+| `/forerunner-arch-review` | `arch-review` | Rank architecture improvement candidates, inspired by Matt Pocock's [`/improve-codebase-architecture`](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) |
 | `/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 |
@@ -118,6 +124,9 @@ pip install codeforerunner
 # Install skills into Claude Code
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# Or via npm
+# npx -y codeforerunner
+
 # In Claude Code:
 # /forerunner-scan     → scans your repo
 # /forerunner-readme   → generates README.md
@@ -139,7 +148,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6.0.2
-      - uses: derek-palmer/codeforerunner@v0.4.3
+      - uses: derek-palmer/codeforerunner@v0.4.5
         with:
           fail-on-drift: "true"   # set "false" to warn-only
 ```
@@ -224,13 +233,13 @@ prompts/
     ├── 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  refresh.md
+    ├── review.md        stack-docs.md  arch-review.md
+    ├── refresh.md
     └── init-agent-onboarding.md
 ```
 
-## Docs and spec
+## Docs
 
-- `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

{codeforerunner-0.4.4 → codeforerunner-0.4.5}/README.md

@@ -2,7 +2,7 @@
 
 # codeForerunner
 
-[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)
+[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.5)](https://socket.dev/npm/package/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.
 
@@ -17,10 +17,15 @@ Install forerunner's prompt pack as skills into your agent CLI. Each documentati
 # One-liner (auto-detects Claude Code, Codex, Gemini CLI)
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# npm
+npx -y codeforerunner
+npm install -g codeforerunner
+
 # Windows
 irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex
 
-# Via forerunner CLI (after pip install)
+# Via Python CLI
+pip install codeforerunner
 forerunner install --all claude
 forerunner install --all codex
 ```
@@ -43,6 +48,7 @@ Then in your agent:
 | `/forerunner-api-docs` | `api-docs` | Generate API reference docs |
 | `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |
 | `/forerunner-flows` | `flows` | Document system flows |
+| `/forerunner-arch-review` | `arch-review` | Rank architecture improvement candidates, inspired by Matt Pocock's [`/improve-codebase-architecture`](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) |
 | `/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 |
@@ -91,6 +97,9 @@ pip install codeforerunner
 # Install skills into Claude Code
 curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash
 
+# Or via npm
+# npx -y codeforerunner
+
 # In Claude Code:
 # /forerunner-scan     → scans your repo
 # /forerunner-readme   → generates README.md
@@ -112,7 +121,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6.0.2
-      - uses: derek-palmer/codeforerunner@v0.4.3
+      - uses: derek-palmer/codeforerunner@v0.4.5
         with:
           fail-on-drift: "true"   # set "false" to warn-only
 ```
@@ -197,13 +206,13 @@ prompts/
     ├── 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  refresh.md
+    ├── review.md        stack-docs.md  arch-review.md
+    ├── refresh.md
     └── init-agent-onboarding.md
 ```
 
-## Docs and spec
+## Docs
 
-- `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

{codeforerunner-0.4.4 → codeforerunner-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeforerunner"
-version = "0.4.4"
+version = "0.4.5"
 description = "Model-agnostic repository documentation tooling (prompt-first; thin CLI)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -50,7 +50,7 @@ forerunner = "codeforerunner.cli:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-codeforerunner = ["py.typed", "prompts/**/*.md"]
+codeforerunner = ["py.typed", "prompts/**/*.md", "tasks.json"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{codeforerunner-0.4.4 → codeforerunner-0.4.5}/src/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/."""
 
 from __future__ import annotations
 
@@ -8,12 +8,21 @@ import sys
 from pathlib import Path
 from typing import Sequence
 
-from codeforerunner.bundle import find_prompts_root, resolve_bundle as _resolve_bundle
-
-SCAN_EXEMPT_TASKS = frozenset({"scan", "init-agent-onboarding"})
+from codeforerunner.bundle import find_prompts_root
+from codeforerunner.prompt_session import Denial, PromptSession
+from codeforerunner.tasks import refresh_tasks as _refresh_tasks
 SCAN_DONE_ENV = "FORERUNNER_SCAN_DONE"
 
 
+def _scan_satisfied(repo_root: Path) -> bool:
+    """CLI scan-first signal: scan artifact present, env override set, or no config to gate."""
+    return (
+        (repo_root / ".forerunner" / "scan.md").is_file()
+        or bool(os.environ.get(SCAN_DONE_ENV))
+        or not (repo_root / "forerunner.config.yaml").is_file()
+    )
+
+
 def _get_bundle(args: argparse.Namespace) -> tuple[str, int]:
     """Resolve bundle for args.task. Returns (bundle_text, exit_code). exit_code != 0 on error."""
     try:
@@ -22,25 +31,22 @@ def _get_bundle(args: argparse.Namespace) -> tuple[str, int]:
         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 (repo_root / "forerunner.config.yaml").is_file()
-        and not os.environ.get(SCAN_DONE_ENV)
-    ):
+    repo_root = Path(args.repo).resolve() if args.repo else Path.cwd()
+    session = PromptSession(prompts_root, _scan_satisfied(repo_root))
+    decision = session.can_run(args.task)
+    if not decision.allowed:
+        if decision.reason is Denial.UNKNOWN_TASK:
+            print(f"error: unknown task '{args.task}'", file=sys.stderr)
+            return "", 2
         print(
-            f"warning: SPEC V2 scan-first — run `forerunner scan` first, "
-            f"then export {SCAN_DONE_ENV}=1 to silence this warning.",
+            f"error: scan-first required — run `forerunner scan` first "
+            f"(writes .forerunner/scan.md). Set {SCAN_DONE_ENV}=1 to skip.",
             file=sys.stderr,
         )
+        return "", 1
 
     try:
-        return _resolve_bundle(prompts_root, args.task), 0
+        return session.bundle_for(args.task), 0
     except FileNotFoundError as e:
         print(f"error: {e}", file=sys.stderr)
         return "", 2
@@ -73,12 +79,12 @@ def cmd_init(args: argparse.Namespace) -> int:
 
 
 def cmd_scan(args: argparse.Namespace) -> int:
-    """Emit the scan prompt bundle and hint about FORERUNNER_SCAN_DONE."""
+    """Emit the scan prompt bundle and hint about scan artifact."""
     rc = _doc_for(args, "scan")
     if rc == 0:
         print(
-            f"hint: export {SCAN_DONE_ENV}=1 in this shell to silence "
-            "scan-first warnings on follow-up `forerunner doc`/`init` calls.",
+            "hint: write the scan result to .forerunner/scan.md to satisfy the "
+            f"scan-first gate on follow-up calls. Or set {SCAN_DONE_ENV}=1 to skip.",
             file=sys.stderr,
         )
     return rc
@@ -111,19 +117,19 @@ def cmd_mcp_server(args: argparse.Namespace) -> int:
     except FileNotFoundError as e:
         print(f"mcp_server: {e}", file=sys.stderr)
         return 2
-    return mcp_server.serve(prompts_root)
+    repo_root = Path(args.repo).resolve() if args.repo else Path.cwd()
+    return mcp_server.serve(prompts_root, repo_root=repo_root)
 
 
 def cmd_refresh(args: argparse.Namespace) -> int:
     """Emit scan + check + all doc-task bundles to stdout for a full doc refresh."""
-    tasks = ["scan", "check", "readme", "api-docs", "stack-docs",
-             "diagrams", "flows", "version-audit", "audit"]
-    for i, task in enumerate(tasks):
+    task_names = [t.name for t in _refresh_tasks()]
+    for i, task in enumerate(task_names):
         ns = argparse.Namespace(repo=getattr(args, "repo", None), task=task)
         rc = cmd_doc(ns)
         if rc != 0:
             return rc
-        if i < len(tasks) - 1:
+        if i < len(task_names) - 1:
             sys.stdout.write("\n---\n\n")
     return 0
 

{codeforerunner-0.4.4 → codeforerunner-0.4.5}/src/codeforerunner/config.py

@@ -1,4 +1,4 @@
-"""`forerunner.config.yaml` schema + loader. See SPEC.md §T25."""
+"""`forerunner.config.yaml` schema + loader."""
 
 from __future__ import annotations
 

{codeforerunner-0.4.4 → codeforerunner-0.4.5}/src/codeforerunner/doctor.py

@@ -1,4 +1,4 @@
-"""`forerunner doctor` — single-screen health report. See SPEC.md §T35."""
+"""`forerunner doctor` — single-screen health report."""
 
 from __future__ import annotations
 

{codeforerunner-0.4.4 → codeforerunner-0.4.5}/src/codeforerunner/installer.py

@@ -1,4 +1,4 @@
-"""Idempotent skill installer. See SPEC.md §D.installer (cites V8, V10, V11, V12)."""
+"""Idempotent skill installer. Re-run safe (V12); body-parity enforced (V10)."""
 
 from __future__ import annotations
 
@@ -10,6 +10,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable, Literal
 
+from codeforerunner.tasks import installable_slugs as _installable_slugs
+
 MARKER_BEGIN = "<!-- forerunner:begin managed=codeforerunner.skill -->"
 MARKER_END = "<!-- forerunner:end -->"
 
@@ -21,22 +23,7 @@ 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",
-)
+TASK_SKILL_SLUGS: tuple[str, ...] = _installable_slugs()
 
 
 @dataclass(frozen=True)

{codeforerunner-0.4.4 → codeforerunner-0.4.5}/src/codeforerunner/mcp_server.py

@@ -1,4 +1,4 @@
-"""Minimal stdio MCP server exposing prompt bundles as tools. See SPEC.md §D.mcp.
+"""Minimal stdio MCP server exposing prompt bundles as tools.
 
 Hand-rolled JSON-RPC 2.0 over line-delimited stdio. Stdlib only.
 """
@@ -11,21 +11,15 @@ from pathlib import Path
 from typing import Any, Iterable
 
 from codeforerunner import __version__ as _pkg_version
-from codeforerunner.bundle import find_prompts_root, resolve_bundle
+from codeforerunner.bundle import find_prompts_root
+from codeforerunner.prompt_session import Denial, PromptSession
+from codeforerunner.tasks import all_tasks as _all_tasks
 
 PROTOCOL_VERSION = "2025-03-26"
 SERVER_NAME = "codeforerunner"
 SERVER_VERSION = _pkg_version
 
 
-def _list_tasks(prompts_root: Path) -> list[Path]:
-    """Return sorted list of task *.md paths under prompts_root/tasks/."""
-    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 '#' and whitespace."""
     with task_path.open(encoding="utf-8") as f:
@@ -38,14 +32,14 @@ def _description_for(task_path: Path) -> str:
 
 
 def _tools(prompts_root: Path) -> list[dict[str, Any]]:
-    """Build MCP tools/list payload from all task files in prompts_root."""
+    """Build MCP tools/list payload from registered tasks."""
     return [
         {
-            "name": p.stem,
-            "description": _description_for(p),
+            "name": task.name,
+            "description": _description_for(prompts_root / "tasks" / f"{task.name}.md"),
             "inputSchema": {"type": "object", "properties": {}, "required": []},
         }
-        for p in _list_tasks(prompts_root)
+        for task in _all_tasks()
     ]
 
 
@@ -59,9 +53,6 @@ def _err(req_id: Any, code: int, message: str) -> dict[str, Any]:
     return {"jsonrpc": "2.0", "id": req_id, "error": {"code": code, "message": message}}
 
 
-SCAN_EXEMPT_TOOLS = frozenset({"init-agent-onboarding", "scan"})
-
-
 def _handle(prompts_root: Path, msg: dict[str, Any], state: dict[str, Any]) -> dict[str, Any] | None:
     """Dispatch a single JSON-RPC message; return response dict or None for notifications."""
     method = msg.get("method")
@@ -94,11 +85,11 @@ def _handle(prompts_root: Path, msg: dict[str, Any], state: dict[str, Any]) -> d
         name = params.get("name")
         if not isinstance(name, str) or "/" in name or "\\" in name or ".." in name:
             return _err(req_id, -32602, f"invalid tool name: {name!r}")
-        task_path = prompts_root / "tasks" / f"{name}.md"
-        tasks_root = (prompts_root / "tasks").resolve()
-        if not task_path.resolve().is_relative_to(tasks_root) 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"):
+        session = PromptSession(prompts_root, scan_satisfied=bool(state.get("scan_called")))
+        decision = session.can_run(name)
+        if not decision.allowed:
+            if decision.reason is Denial.UNKNOWN_TASK:
+                return _err(req_id, -32602, f"unknown tool: {name!r}")
             return _err(
                 req_id,
                 -32000,
@@ -107,7 +98,7 @@ def _handle(prompts_root: Path, msg: dict[str, Any], state: dict[str, Any]) -> d
         if name == "scan":
             state["scan_called"] = True
         try:
-            text = resolve_bundle(prompts_root, name)
+            text = session.bundle_for(name)
         except Exception as e:  # pragma: no cover - defensive
             return _err(req_id, -32603, f"internal error: {e}")
         return _ok(
@@ -118,9 +109,17 @@ def _handle(prompts_root: Path, msg: dict[str, Any], state: dict[str, Any]) -> d
     return _err(req_id, -32601, f"method not found: {method!r}")
 
 
-def serve(prompts_root: Path, stdin: Iterable[str] = sys.stdin, stdout=sys.stdout, stderr=sys.stderr) -> int:
+def serve(
+    prompts_root: Path,
+    repo_root: Path | None = None,
+    stdin: Iterable[str] = sys.stdin,
+    stdout=sys.stdout,
+    stderr=sys.stderr,
+) -> int:
     """Run the JSON-RPC 2.0 MCP server loop over *stdin*/*stdout* until EOF."""
-    state: dict[str, Any] = {"scan_called": False, "initialized": False}
+    root = repo_root if repo_root is not None else Path.cwd()
+    scan_artifact = root / ".forerunner" / "scan.md"
+    state: dict[str, Any] = {"scan_called": scan_artifact.is_file(), "initialized": False}
     for raw in stdin:
         line = raw.strip()
         if not line:
@@ -153,7 +152,7 @@ def main(argv: list[str] | None = None) -> int:
     except FileNotFoundError as e:
         print(f"mcp_server: {e}", file=sys.stderr)
         return 2
-    return serve(prompts_root)
+    return serve(prompts_root, repo_root=Path.cwd().resolve())
 
 
 if __name__ == "__main__":  # pragma: no cover

codeforerunner-0.4.5/src/codeforerunner/prompt_session.py

@@ -0,0 +1,53 @@
+"""Prompt Session — run-scoped owner of task lookup and scan-first enforcement.
+
+CLI and MCP are thin adapters: they construct a session, ask whether a task
+can run, and translate the structured Decision into their own surface
+(stdout/exit codes for CLI, JSON-RPC for MCP). The session unifies the
+scan-first *rule*; each adapter still computes its own scan-satisfied signal
+and injects it (see docs/adr/0001).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from pathlib import Path
+
+from codeforerunner import tasks
+from codeforerunner.bundle import resolve_bundle
+
+
+class Denial(Enum):
+    UNKNOWN_TASK = auto()
+    SCAN_REQUIRED = auto()
+
+
+@dataclass(frozen=True)
+class Decision:
+    allowed: bool
+    task: tasks.Task | None = None
+    reason: Denial | None = None
+    message: str | None = None
+
+
+class PromptSession:
+    def __init__(self, prompts_root: Path, scan_satisfied: bool) -> None:
+        self._prompts_root = prompts_root
+        self._scan_done = scan_satisfied
+
+    def mark_scan_done(self) -> None:
+        """Record that scan ran in this session (MCP adapter, after scan tool)."""
+        self._scan_done = True
+
+    def can_run(self, name: str) -> Decision:
+        try:
+            task = tasks.get(name)
+        except KeyError:
+            return Decision(False, reason=Denial.UNKNOWN_TASK, message=f"unknown task: {name!r}")
+        if task.scan_exempt or self._scan_done:
+            return Decision(True, task=task)
+        return Decision(False, task=task, reason=Denial.SCAN_REQUIRED, message="scan-first required")
+
+    def bundle_for(self, name: str) -> str:
+        """Resolve the prompt bundle text for *name*. Call only after can_run allows."""
+        return resolve_bundle(self._prompts_root, name)

codeforerunner-0.4.5/src/codeforerunner/prompts/tasks/arch-review.md

@@ -0,0 +1,121 @@
+# Task: Architecture Review
+
+Inspired by Matt Pocock's `/improve-codebase-architecture` skill:
+https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture
+
+Ranks repo-grounded Deepening Opportunities: architecture improvements that hide more behavior behind smaller interfaces, increasing leverage for callers and locality for maintainers.
+Requires scan result as input.
+
+## Input
+
+- Scan result from `prompts/tasks/scan.md`
+- File tree
+- Key module/package files relevant to the scan result
+- Existing tests for the modules under review
+- `CONTEXT.md` or `CONTEXT-MAP.md` if present
+- Relevant `docs/adr/*.md` files if present
+- Existing architecture docs only when they clarify current design
+
+## Review Focus
+
+Look for architecture friction, not documentation drift:
+
+1. Modules that are shallow: interface complexity nearly matches implementation complexity
+2. Concepts that require bouncing across many files to understand
+3. Seams that leak implementation details into callers
+4. Pure helpers extracted for testability while real behavior remains hard to test
+5. Adapter seams with more abstraction than real variation
+6. Missing or weak tests caused by poor locality
+
+Apply the deletion test to suspected shallow modules: if deleting the module makes complexity disappear, it was probably a pass-through; if complexity reappears across many callers, it was earning its keep.
+
+## Vocabulary
+
+Use these architecture terms consistently:
+
+- Module
+- Interface
+- Implementation
+- Deep
+- Shallow
+- Seam
+- Adapter
+- Leverage
+- Locality
+- Deepening Opportunity
+- Deletion test
+
+Use repo vocabulary from `CONTEXT.md` when present. If the repo lacks `CONTEXT.md` or the vocabulary is incomplete, infer temporary terms from evidence and list them under `## Suggested Glossary Additions`; do not write or rewrite `CONTEXT.md`.
+
+## Candidate Format
+
+For each Deepening Opportunity, include:
+
+- **Files/modules**: concrete files or modules involved
+- **Problem**: architecture friction observed
+- **Evidence**: repo evidence supporting the finding
+- **Proposed direction**: plain-English direction only
+- **Benefits**: locality and leverage improvements
+- **Testing impact**: what becomes easier to verify, without final test code
+- **Risk / blast radius**: likely scope and migration risk
+- **Recommendation strength**: `Strong`, `Worth exploring`, or `Speculative`
+
+## Rules
+
+- Claims must derive from provided files. If evidence is absent, omit or document in `## Gaps`.
+- Do not report stale README/API/diagram/doc drift; use `check`, `review`, `diagrams`, or `flows` for that.
+- Do not propose final function signatures, dataclass fields, schema shapes, or file-by-file implementation plans.
+- Do not mutate `CONTEXT.md` or create ADRs.
+- Do not imply Matt Pocock endorses codeforerunner.
+- Keep the highest-signal 3-7 candidates. Fewer is acceptable when evidence is thin.
+
+## Output Format
+
+<!-- output: .forerunner/arch-review.md -->
+
+# Architecture Review
+
+> Inspired by Matt Pocock's `/improve-codebase-architecture` skill:
+> https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture
+
+## Summary
+
+One paragraph describing the main architecture pressure observed.
+
+## Top Recommendation
+
+Name the highest-value Deepening Opportunity and why it should be first.
+
+## Deepening Opportunities
+
+### 1. [Candidate Name]
+
+**Recommendation strength:** Strong | Worth exploring | Speculative
+
+**Files/modules:** ...
+
+**Problem:** ...
+
+**Evidence:** ...
+
+**Proposed direction:** ...
+
+**Benefits:** ...
+
+**Testing impact:** ...
+
+**Risk / blast radius:** ...
+
+## Suggested Glossary Additions
+
+Only include if `CONTEXT.md` is missing or incomplete. Suggest terms; do not write them.
+
+## Not Yet Decided
+
+- Final interface shapes
+- Migration sequence
+- Exact tests
+
+## Gaps
+
+List missing evidence that could materially change the review.

{codeforerunner-0.4.4 → codeforerunner-0.4.5}/src/codeforerunner/prompts/tasks/init-agent-onboarding.md

@@ -10,7 +10,11 @@ Prompt-first workflow for manual use today; future wrappers may orchestrate it.
 - Existing instruction files if present:
   - `AGENTS.md`
   - `CLAUDE.md`, `.cursor/rules/*`, `.cursorrules`, `.github/copilot-instructions.md`, `opencode.json`
-- Key docs describing current state (`README.md`, `SPEC.md`, roadmap docs)
+- Existing domain vocabulary files if present:
+  - `CONTEXT.md`
+  - `CONTEXT-MAP.md`
+  - relevant `docs/adr/*.md`
+- Key docs describing current state (`README.md`, `AGENTS.md`, roadmap docs)
 - Optional prior scan result from `prompts/tasks/scan.md`
 
 ## Objectives
@@ -18,6 +22,7 @@ Prompt-first workflow for manual use today; future wrappers may orchestrate it.
 1. Build or refine `AGENTS.md` so future agent sessions ramp quickly.
 2. Keep only high-signal, repo-specific guidance likely to prevent mistakes.
 3. Reconcile instruction drift across files without deleting valid custom constraints.
+4. Create or refine `CONTEXT.md` when stable repo-specific domain terms are evident.
 
 ## Method
 
@@ -26,6 +31,7 @@ Prompt-first workflow for manual use today; future wrappers may orchestrate it.
 3. Keep sections short and scannable.
 4. Remove stale or generic guidance.
 5. Preserve useful constraints that remain true.
+6. For `CONTEXT.md`, include only stable repo-specific vocabulary. Do not add generic technology terms unless this repo gives them product-specific meaning.
 
 ## Required Output Sections
 
@@ -39,6 +45,9 @@ Prompt-first workflow for manual use today; future wrappers may orchestrate it.
 
 - Never invent runnable surfaces (CLI, CI, hooks, Docker, package publish) if files do not exist.
 - Never copy broad best-practice text that is not repo-specific.
+- Create or update `CONTEXT.md` only when stable repo-specific terms exist in tracked files or established conversation context.
+- If only generic technical words are available, do not create `CONTEXT.md`; mention the absence under `## Gaps` if relevant.
+- Keep `CONTEXT.md` as a glossary only: no implementation plan, scratch notes, or file-by-file design decisions.
 - Claims must derive from provided files. If evidence is absent, omit or document in `## Gaps`.
 - If uncertain, omit.
 - Keep naming consistent with repo conventions.
@@ -46,3 +55,7 @@ Prompt-first workflow for manual use today; future wrappers may orchestrate it.
 ## Output
 
 <!-- output: AGENTS.md -->
+
+When stable domain vocabulary exists, also output:
+
+<!-- output: CONTEXT.md -->

{codeforerunner-0.4.4 → codeforerunner-0.4.5}/src/codeforerunner/prompts/tasks/scan.md

@@ -90,3 +90,5 @@ gaps:
 ```
 
 Wrap output in a fenced yaml block. No prose before or after.
+
+<!-- output: .forerunner/scan.md -->