codex-coach 0.1.0 → 0.1.3

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-coach",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Local-first Codex usage coach that analyzes logs and suggests workflow improvements.",
   "author": {
     "name": "Codex Coach Contributors"

package/README.md

@@ -1,6 +1,6 @@
 # Codex Coach
 
-![Codex Coach logo](https://cdn.jsdelivr.net/npm/codex-coach@0.1.0/assets/brand/codex-coach-logo.png)
+![Codex Coach banner](assets/brand/codex-coach-banner.png)
 
 Codex Coach is a local-first usage coach for Codex users. It reads Codex session logs on your machine, generates redacted habit reports, and suggests reviewable improvements to your Codex configuration and project instructions.
 
@@ -48,6 +48,9 @@ codex-coach scan --since 7d
 codex-coach report --since 7d
 codex-coach report --since 7d --mode expert
 codex-coach suggest-config
+codex-coach instructions scan --since 30d
+codex-coach instructions report --since 30d
+codex-coach instructions suggest --since 30d
 codex-coach lint-prompt "fix the failing auth test and verify pytest passes"
 ```
 
@@ -71,6 +74,7 @@ Suggest custom instruction changes
 - `~/.codex-coach/reports/latest.md`
 - `~/.codex-coach/reports/weekly-YYYY-MM-DD.md`
 - `~/.codex-coach/facts/latest.json`
+- `~/.codex-coach/instructions/index.json`
 - `~/.codex-coach/suggestions/*.patch.md`
 
 ## Coaching Features
@@ -81,17 +85,10 @@ Suggest custom instruction changes
 - Beginner and expert report modes.
 - Skill opportunities: repeated workflow patterns that may deserve a reusable Codex skill.
 - Real-time prompt linting through `codex-coach lint-prompt`.
-
-## Visual Examples
-
-![How Codex Coach works](https://cdn.jsdelivr.net/npm/codex-coach@0.1.0/assets/examples/how-it-works.png)
-
-![Prompt lint example](https://cdn.jsdelivr.net/npm/codex-coach@0.1.0/assets/examples/prompt-lint.png)
-
-![Project capsules example](https://cdn.jsdelivr.net/npm/codex-coach@0.1.0/assets/examples/project-capsules.png)
+- Instruction Playbook Audit: review global custom instructions and project `AGENTS.md` files for stale mode locks, scope leaks, missing verification rules, secrets, and active projects without a playbook.
 
 ## Brand Assets
 
-- Wide logo: `assets/brand/codex-coach-logo.png`
+- Main README banner: `assets/brand/codex-coach-banner.png`
+- Wide logo/social preview: `assets/brand/codex-coach-logo.png`
 - Square icon: `assets/brand/codex-coach-icon.png`
-- Editable SVG sources live beside each PNG.

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "codex-coach",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Local-first Codex usage coach and plugin",
   "license": "MIT",
   "author": "Codex Coach Contributors",
+  "homepage": "https://github.com/johnvouros/codexcoach#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnvouros/codexcoach.git"
+  },
+  "bugs": {
+    "url": "https://github.com/johnvouros/codexcoach/issues"
+  },
   "type": "commonjs",
   "bin": {
     "codex-coach": "bin/codex-coach.js"
@@ -12,6 +20,9 @@
     "assets/",
     "bin/",
     "src/",
+    "!src/**/__pycache__/**",
+    "!src/**/*.pyc",
+    "!src/**/*.pyo",
     "skills/",
     ".codex-plugin/",
     "install.sh",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-coach"
-version = "0.1.0"
+version = "0.1.3"
 description = "Local-first Codex usage coach and plugin"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -13,6 +13,11 @@ authors = [{ name = "Codex Coach Contributors" }]
 keywords = ["codex", "ai", "developer-tools", "analytics", "prompting"]
 dependencies = []
 
+[project.urls]
+Homepage = "https://github.com/johnvouros/codexcoach"
+Repository = "https://github.com/johnvouros/codexcoach"
+Issues = "https://github.com/johnvouros/codexcoach/issues"
+
 [project.scripts]
 codex-coach = "codex_coach.cli:main"
 

package/skills/codex-coach/SKILL.md

@@ -36,13 +36,20 @@ codex-coach report --since 7d --mode expert
 codex-coach suggest-config --since 7d
 ```
 
-6. For a prompt the user is drafting, lint it directly:
+6. For custom instructions or `AGENTS.md` health, run the playbook audit:
+
+```sh
+codex-coach instructions report --since 30d
+codex-coach instructions suggest --since 30d
+```
+
+7. For a prompt the user is drafting, lint it directly:
 
 ```sh
 codex-coach lint-prompt "fix the login bug"
 ```
 
-7. Explain that suggestions are reviewable and are not applied automatically.
+8. Explain that suggestions are reviewable and are not applied automatically.
 
 ## User Modes
 
@@ -56,6 +63,7 @@ codex-coach lint-prompt "fix the login bug"
 - Prompt rewrites: show the redacted preview and the safer template, not the raw original prompt.
 - Confidence: keep low-confidence suggestions tentative; high-confidence suggestions can be presented as the next best habit.
 - Skill opportunities: if the report flags a repeated workflow, suggest a small user skill with trigger, context to gather, verification commands, and resume rules.
+- Instruction Playbook: surface stale mode locks, project-specific global rules, missing project playbooks, missing verification cues, and secret-shaped values without quoting raw instruction text.
 
 ## Guardrails
 

package/skills/codex-coach/references/config-suggestions.md

@@ -33,3 +33,13 @@ For repeated workflows, prefer a user skill over a long global instruction:
 ```md
 When this workflow appears, gather [project context], follow [steps], verify with [commands], and resume from [ledger/checklist] after interruption.
 ```
+
+Instruction Playbook Audit checks:
+
+- Stale mode locks: standing rules such as "research only" or "do not implement" that may belong to a temporary task mode.
+- Scope leaks: stack, UI style, or command rules in global custom instructions that should live in a project `AGENTS.md`.
+- Missing verification cues: active projects with implementation-heavy usage but no test/build/lint/verify guidance.
+- Missing playbooks: active project directories with no discovered nearby `AGENTS.md`.
+- Safety issues: secret-shaped values or credentials in instruction files.
+
+Suggested edits should be small, reversible, and phrased as snippets for the user to review.

package/skills/codex-coach/references/privacy.md

@@ -6,13 +6,14 @@ Default inputs:
 
 - `~/.codex/sessions/**/*.jsonl`
 - `~/.codex/archived_sessions/*.jsonl`
-- Optional Codex config and project metadata only when a user asks for deeper recommendations.
+- Optional Codex config, global instruction files, and project `AGENTS.md` metadata for Instruction Playbook Audit.
 
 Default outputs:
 
 - `~/.codex-coach/facts/latest.json`
 - `~/.codex-coach/reports/latest.md`
 - `~/.codex-coach/reports/weekly-YYYY-MM-DD.md`
+- `~/.codex-coach/instructions/index.json`
 - `~/.codex-coach/suggestions/*.patch.md`
 
 Default redaction:
@@ -23,3 +24,4 @@ Default redaction:
 - Prompt rewrites are generated as generic templates and do not include raw private details.
 - Project capsules use redacted project labels instead of full local paths.
 - Config suggestions are written as review files and are not applied automatically.
+- Instruction audits store hashes, sizes, categories, and suggested snippets; they do not write raw instruction file bodies to reports or facts.

package/src/codex_coach/cli.py

@@ -6,11 +6,19 @@ import sys
 from datetime import UTC, datetime
 from pathlib import Path
 
+from .instruction_audit import analyze_instructions
 from .install import install_from_source, uninstall
 from .parser import iter_log_paths, scan_logs
 from .paths import default_paths
 from .prompts import score_prompt
-from .reports import render_markdown_report, write_json_facts, write_markdown_report, write_suggestion_files
+from .reports import (
+    render_instruction_report,
+    render_markdown_report,
+    write_instruction_suggestion_files,
+    write_json_facts,
+    write_markdown_report,
+    write_suggestion_files,
+)
 from .timeutil import parse_since
 
 
@@ -34,6 +42,15 @@ def main(argv: list[str] | None = None) -> int:
     suggest = sub.add_parser("suggest-config", help="Write reviewable config suggestion files")
     suggest.add_argument("--since", default="7d")
 
+    instructions = sub.add_parser("instructions", help="Audit Codex custom instructions and project AGENTS.md files")
+    instructions_sub = instructions.add_subparsers(dest="instructions_command", required=True)
+    instructions_scan = instructions_sub.add_parser("scan", help="Write instruction audit facts")
+    instructions_scan.add_argument("--since", default="30d")
+    instructions_report = instructions_sub.add_parser("report", help="Write an instruction playbook report")
+    instructions_report.add_argument("--since", default="30d")
+    instructions_suggest = instructions_sub.add_parser("suggest", help="Write reviewable instruction suggestion files")
+    instructions_suggest.add_argument("--since", default="30d")
+
     lint = sub.add_parser("lint-prompt", help="Score one prompt and suggest a safer rewrite")
     lint.add_argument("prompt", nargs="*", help="Prompt text. Reads stdin when omitted.")
     lint.add_argument("--json", action="store_true", help="Write machine-readable JSON")
@@ -68,6 +85,8 @@ def main(argv: list[str] | None = None) -> int:
             for path in written:
                 print(f"Wrote suggestion {path}")
             return 0
+        if args.command == "instructions":
+            return _instructions(paths, args.instructions_command, args.since)
         if args.command == "lint-prompt":
             prompt_text = " ".join(args.prompt).strip() if args.prompt else sys.stdin.read().strip()
             return _lint_prompt(prompt_text, as_json=args.json)
@@ -94,11 +113,47 @@ def _scan(paths, since: str) -> dict:
     since_dt = parse_since(since)
     paths.ensure_output_dirs()
     facts = scan_logs(paths.codex_home, since_dt=since_dt, since_label=since)
+    facts["instruction_audit"] = analyze_instructions(
+        paths.home,
+        paths.codex_home,
+        since_dt=since_dt,
+        since_label=since,
+        usage_facts=facts,
+    )
     facts["generated_at"] = datetime.now(UTC).isoformat(timespec="seconds")
     write_json_facts(facts, paths.facts_dir / "latest.json")
+    write_json_facts(facts["instruction_audit"], paths.instructions_dir / "index.json")
     return facts
 
 
+def _instructions(paths, command: str, since: str) -> int:
+    facts = _scan(paths, since)
+    audit = facts.get("instruction_audit", {})
+    if command == "scan":
+        print(f"Wrote instruction audit to {paths.instructions_dir / 'index.json'}")
+        return 0
+    if command == "report":
+        generated_at = datetime.now(UTC)
+        report_text = render_instruction_report(audit, generated_at=generated_at)
+        paths.reports_dir.mkdir(parents=True, exist_ok=True)
+        latest = paths.reports_dir / "instructions-latest.md"
+        weekly = paths.reports_dir / f"instructions-{generated_at.date().isoformat()}.md"
+        latest.write_text(report_text, encoding="utf-8")
+        weekly.write_text(report_text, encoding="utf-8")
+        print(f"Wrote instruction report to {latest}")
+        print(f"Wrote dated copy to {weekly}")
+        return 0
+    if command == "suggest":
+        written = write_instruction_suggestion_files(audit, paths.suggestions_dir)
+        if written:
+            for path in written:
+                print(f"Wrote instruction suggestion {path}")
+        else:
+            print("No instruction suggestions found")
+        return 0
+    raise ValueError(f"unknown instructions command: {command}")
+
+
 def _doctor(paths) -> int:
     log_paths = iter_log_paths(paths.codex_home)
     print(f"home: {paths.home}")
@@ -106,6 +161,7 @@ def _doctor(paths) -> int:
     print(f"coach_home: {paths.coach_home}")
     print(f"log_files: {len(log_paths)}")
     print(f"reports_dir: {paths.reports_dir}")
+    print(f"instructions_dir: {paths.instructions_dir}")
     command = paths.home / ".local" / "bin" / "codex-coach"
     print(f"command: {command} {'OK' if command.exists() else 'not installed'}")
     plugin = paths.home / "plugins" / "codex-coach" / ".codex-plugin" / "plugin.json"

package/src/codex_coach/install.py

@@ -15,7 +15,8 @@ def install_from_source(source_root: Path, paths: CoachPaths, *, schedule: str =
     paths.ensure_output_dirs()
     paths.coach_home.mkdir(parents=True, exist_ok=True)
     _write_default_config(paths, schedule=schedule)
-    _copy_app(source_root, paths.app_dir)
+    if source_root != paths.app_dir.resolve():
+        _copy_app(source_root, paths.app_dir)
     _install_command(paths)
     plugin_path = _install_plugin(source_root, paths.home)
     skill_paths = _install_user_skills(source_root, paths.home)