Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
626a3e6497 | ||
|
|
9d56d371a5 | ||
|
|
1d1a4e123b | ||
|
|
2c3fc5647f | ||
|
|
ad738b3df0 | ||
|
|
65a7331968 | ||
|
|
bb3a21ab0d | ||
|
|
02a4ad6034 | ||
|
|
c7f89340d6 |
@@ -0,0 +1,61 @@
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{
|
||||
"matcher": "startup|resume",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "sh .codex/hooks/session-start.sh 2>/dev/null || sh \"$HOME/.codex/hooks/session-start.sh\" 2>/dev/null || true",
|
||||
"statusMessage": "Loading planning context"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "sh .codex/hooks/user-prompt-submit.sh 2>/dev/null || sh \"$HOME/.codex/hooks/user-prompt-submit.sh\" 2>/dev/null || true"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Bash",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "python3 .codex/hooks/pre_tool_use.py 2>/dev/null || python3 \"$HOME/.codex/hooks/pre_tool_use.py\" 2>/dev/null || true",
|
||||
"statusMessage": "Checking plan before Bash"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Bash",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "python3 .codex/hooks/post_tool_use.py 2>/dev/null || python3 \"$HOME/.codex/hooks/post_tool_use.py\" 2>/dev/null || true",
|
||||
"statusMessage": "Reviewing Bash against plan"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"Stop": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "python3 .codex/hooks/stop.py 2>/dev/null || python3 \"$HOME/.codex/hooks/stop.py\" 2>/dev/null || true",
|
||||
"timeout": 30
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,66 @@
|
||||
#!/usr/bin/env python3
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
|
||||
HOOK_DIR = Path(__file__).resolve().parent
|
||||
|
||||
|
||||
def load_payload() -> dict[str, Any]:
|
||||
raw = sys.stdin.read().strip()
|
||||
if not raw:
|
||||
return {}
|
||||
try:
|
||||
payload = json.loads(raw)
|
||||
except json.JSONDecodeError:
|
||||
return {}
|
||||
return payload if isinstance(payload, dict) else {}
|
||||
|
||||
|
||||
def cwd_from_payload(payload: dict[str, Any]) -> Path:
|
||||
cwd = payload.get("cwd")
|
||||
if isinstance(cwd, str) and cwd:
|
||||
return Path(cwd)
|
||||
return Path.cwd()
|
||||
|
||||
|
||||
def emit_json(payload: dict[str, Any]) -> None:
|
||||
if not payload:
|
||||
return
|
||||
json.dump(payload, sys.stdout, ensure_ascii=False)
|
||||
sys.stdout.write("\n")
|
||||
|
||||
|
||||
def parse_json(text: str) -> dict[str, Any]:
|
||||
if not text.strip():
|
||||
return {}
|
||||
try:
|
||||
payload = json.loads(text)
|
||||
except json.JSONDecodeError:
|
||||
return {}
|
||||
return payload if isinstance(payload, dict) else {}
|
||||
|
||||
|
||||
def run_shell_script(script_name: str, cwd: Path) -> tuple[str, str]:
|
||||
result = subprocess.run(
|
||||
["sh", str(HOOK_DIR / script_name)],
|
||||
cwd=str(cwd),
|
||||
text=True,
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
return result.stdout.strip(), result.stderr.strip()
|
||||
|
||||
|
||||
def main_guard(func) -> int:
|
||||
try:
|
||||
func()
|
||||
except Exception as exc: # pragma: no cover
|
||||
print(f"[planning-with-files hook] {exc}", file=sys.stderr)
|
||||
return 0
|
||||
return 0
|
||||
@@ -0,0 +1,8 @@
|
||||
#!/bin/bash
|
||||
# planning-with-files: Post-tool-use hook for Codex
|
||||
# Reused from the Cursor integration.
|
||||
|
||||
if [ -f task_plan.md ]; then
|
||||
echo "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
|
||||
fi
|
||||
exit 0
|
||||
@@ -0,0 +1,16 @@
|
||||
#!/usr/bin/env python3
|
||||
from __future__ import annotations
|
||||
|
||||
import codex_hook_adapter as adapter
|
||||
|
||||
|
||||
def main() -> None:
|
||||
payload = adapter.load_payload()
|
||||
root = adapter.cwd_from_payload(payload)
|
||||
stdout, _ = adapter.run_shell_script("post-tool-use.sh", root)
|
||||
if stdout:
|
||||
adapter.emit_json({"systemMessage": stdout})
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(adapter.main_guard(main))
|
||||
@@ -0,0 +1,13 @@
|
||||
#!/bin/bash
|
||||
# planning-with-files: Pre-tool-use hook for Codex
|
||||
# Reused from the Cursor integration.
|
||||
|
||||
PLAN_FILE="task_plan.md"
|
||||
|
||||
if [ -f "$PLAN_FILE" ]; then
|
||||
# Log plan context to stderr so the Codex adapter can surface it as systemMessage.
|
||||
head -30 "$PLAN_FILE" >&2
|
||||
fi
|
||||
|
||||
echo '{"decision": "allow"}'
|
||||
exit 0
|
||||
@@ -0,0 +1,23 @@
|
||||
#!/usr/bin/env python3
|
||||
from __future__ import annotations
|
||||
|
||||
import codex_hook_adapter as adapter
|
||||
|
||||
|
||||
def main() -> None:
|
||||
payload = adapter.load_payload()
|
||||
root = adapter.cwd_from_payload(payload)
|
||||
stdout, stderr = adapter.run_shell_script("pre-tool-use.sh", root)
|
||||
|
||||
result = adapter.parse_json(stdout)
|
||||
decision = result.get("decision")
|
||||
if decision and decision != "allow":
|
||||
adapter.emit_json(result)
|
||||
return
|
||||
|
||||
if stderr:
|
||||
adapter.emit_json({"systemMessage": stderr})
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(adapter.main_guard(main))
|
||||
@@ -0,0 +1,15 @@
|
||||
#!/bin/sh
|
||||
# planning-with-files: SessionStart hook for Codex
|
||||
# Runs session catchup, then reuses the same prompt context hook as UserPromptSubmit.
|
||||
|
||||
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
|
||||
CODEX_ROOT="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)"
|
||||
SKILL_DIR="$CODEX_ROOT/skills/planning-with-files"
|
||||
PYTHON_BIN="${PYTHON_BIN:-$(command -v python3 || command -v python)}"
|
||||
|
||||
if [ -n "$PYTHON_BIN" ] && [ -f "$SKILL_DIR/scripts/session-catchup.py" ]; then
|
||||
"$PYTHON_BIN" "$SKILL_DIR/scripts/session-catchup.py" "$(pwd)"
|
||||
fi
|
||||
|
||||
sh "$SCRIPT_DIR/user-prompt-submit.sh"
|
||||
exit 0
|
||||
@@ -0,0 +1,29 @@
|
||||
#!/usr/bin/env python3
|
||||
from __future__ import annotations
|
||||
|
||||
import codex_hook_adapter as adapter
|
||||
|
||||
|
||||
def main() -> None:
|
||||
payload = adapter.load_payload()
|
||||
root = adapter.cwd_from_payload(payload)
|
||||
stdout, _ = adapter.run_shell_script("stop.sh", root)
|
||||
result = adapter.parse_json(stdout)
|
||||
|
||||
message = result.get("followup_message")
|
||||
if not isinstance(message, str) or not message:
|
||||
return
|
||||
|
||||
if "ALL PHASES COMPLETE" in message:
|
||||
adapter.emit_json({"systemMessage": message})
|
||||
return
|
||||
|
||||
if bool(payload.get("stop_hook_active")):
|
||||
adapter.emit_json({"systemMessage": message})
|
||||
return
|
||||
|
||||
adapter.emit_json({"decision": "block", "reason": message})
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(adapter.main_guard(main))
|
||||
@@ -0,0 +1,33 @@
|
||||
#!/bin/bash
|
||||
# planning-with-files: Stop hook for Codex
|
||||
# Reused from the Cursor integration; Codex adapts followup_message separately.
|
||||
|
||||
PLAN_FILE="task_plan.md"
|
||||
|
||||
if [ ! -f "$PLAN_FILE" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
|
||||
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
|
||||
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
|
||||
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
|
||||
|
||||
if [ "$COMPLETE" -eq 0 ] && [ "$IN_PROGRESS" -eq 0 ] && [ "$PENDING" -eq 0 ]; then
|
||||
COMPLETE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
|
||||
IN_PROGRESS=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
|
||||
PENDING=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
|
||||
fi
|
||||
|
||||
: "${TOTAL:=0}"
|
||||
: "${COMPLETE:=0}"
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
echo "{\"followup_message\": \"[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting.\"}"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "{\"followup_message\": \"[planning-with-files] Task incomplete ($COMPLETE/$TOTAL phases done). Update progress.md, then read task_plan.md and continue working on the remaining phases.\"}"
|
||||
exit 0
|
||||
@@ -0,0 +1,14 @@
|
||||
#!/bin/bash
|
||||
# planning-with-files: User prompt submit hook for Codex
|
||||
# Reused from the Cursor integration.
|
||||
|
||||
if [ -f task_plan.md ]; then
|
||||
echo "[planning-with-files] ACTIVE PLAN — current state:"
|
||||
head -50 task_plan.md
|
||||
echo ""
|
||||
echo "=== recent progress ==="
|
||||
tail -20 progress.md 2>/dev/null
|
||||
echo ""
|
||||
echo "[planning-with-files] Read findings.md for research context. Continue from the current phase."
|
||||
fi
|
||||
exit 0
|
||||
@@ -23,7 +23,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SD=\"${CODEX_SKILL_ROOT:-$HOME/.codex/skills/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
|
||||
metadata:
|
||||
version: "2.23.0"
|
||||
version: "2.30.0"
|
||||
---
|
||||
|
||||
# Planning with Files
|
||||
|
||||
Regular → Executable
Regular → Executable
Regular → Executable
@@ -2,6 +2,63 @@
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
## [2.30.0] - 2026-04-03
|
||||
|
||||
### Changed
|
||||
|
||||
- **Migrate from `${CLAUDE_PLUGIN_ROOT}` to `${CLAUDE_SKILL_DIR}`** in main SKILL.md
|
||||
- Stop hook, session-catchup path, and templates path now use `${CLAUDE_SKILL_DIR}` (added in Claude Code v2.1.69)
|
||||
- 3-level fallback chain for backward compatibility: `CLAUDE_SKILL_DIR` -> `CLAUDE_PLUGIN_ROOT` -> hardcoded path
|
||||
- Default fallback path updated from `.claude/plugins/planning-with-files` to `.claude/skills/planning-with-files` (matches `npx skills add` install location)
|
||||
- Fixes path resolution failures on Windows and Linux (related to #32)
|
||||
|
||||
### Restructured
|
||||
|
||||
- **IDE-specific configurations moved to dedicated branches**
|
||||
- Master branch now contains only the core skill, templates, scripts, and docs
|
||||
- Each IDE has its own branch: `ide/cursor`, `ide/copilot`, `ide/gemini`, `ide/kiro`, `ide/codex`, `ide/mastra`, `ide/codebuddy`, `ide/factory`, `ide/opencode`, `ide/continue`, `ide/pi-agent`
|
||||
- README updated with branch reference table
|
||||
- Reduces master branch clutter and makes per-IDE maintenance independent
|
||||
|
||||
---
|
||||
|
||||
## [2.29.0] - 2026-03-24
|
||||
|
||||
### Added
|
||||
|
||||
- **Analytics workflow template** (PR #115 by @mvanhorn, addresses #103)
|
||||
- New `--template analytics` flag on `init-session.sh` and `init-session.ps1`
|
||||
- `templates/analytics_task_plan.md` with 4 analytics-specific phases: Data Discovery, Exploratory Analysis, Hypothesis Testing, Synthesis
|
||||
- `templates/analytics_findings.md` with Data Sources table, Hypothesis Log, Query Results, and Statistical Findings sections
|
||||
- Analytics-specific `progress.md` generates a Query Log table instead of Test Results
|
||||
- Default behavior unchanged; existing users are not affected
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
./scripts/init-session.sh --template analytics my-project
|
||||
```
|
||||
|
||||
### Thanks
|
||||
|
||||
- @mvanhorn (Matt Van Horn) for implementing the analytics template that @sedlukha requested in #103
|
||||
|
||||
---
|
||||
|
||||
## [2.28.0] - 2026-03-22
|
||||
|
||||
### Added
|
||||
|
||||
- **Traditional Chinese (zh-TW) skill variant** (PR #113 by @waynelee2048)
|
||||
- Fully translated SKILL.md, templates, and scripts under `skills/planning-with-files-zht/`
|
||||
- Localized hooks, check-complete, init-session, and session-catchup scripts
|
||||
|
||||
### Thanks
|
||||
|
||||
- @waynelee2048 for the Traditional Chinese translation
|
||||
|
||||
---
|
||||
|
||||
## [2.27.0] - 2026-03-20
|
||||
|
||||
### Added
|
||||
|
||||
+9
-2
@@ -82,6 +82,13 @@ These amazing people have contributed code, documentation, or significant improv
|
||||
- Added Pi Agent support with full skill integration
|
||||
- **Impact:** Expands the skill to the Pi Agent ecosystem
|
||||
|
||||
- **[@mvanhorn](https://github.com/mvanhorn)** (Matt Van Horn) - [PR #115](https://github.com/OthmanAdi/planning-with-files/pull/115)
|
||||
- Added analytics workflow template with `--template analytics` flag on `init-session.sh` and `init-session.ps1`
|
||||
- Created `analytics_task_plan.md` with 4 analytics-specific phases (Data Discovery, Exploratory Analysis, Hypothesis Testing, Synthesis)
|
||||
- Created `analytics_findings.md` with Data Sources table, Hypothesis Log, Query Results, and Statistical Findings sections
|
||||
- Analytics-specific `progress.md` with Query Log replacing Test Results
|
||||
- **Impact:** Extends the planning pattern to data analytics workflows (addresses #103)
|
||||
|
||||
### Other Contributors
|
||||
|
||||
- **[@popey](https://github.com/popey)** - [PR #83](https://github.com/OthmanAdi/planning-with-files/pull/83)
|
||||
@@ -185,6 +192,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
|
||||
|
||||
---
|
||||
|
||||
**Total Contributors:** 26+ and growing!
|
||||
**Total Contributors:** 27+ and growing!
|
||||
|
||||
*Last updated: March 22, 2026*
|
||||
*Last updated: March 24, 2026*
|
||||
|
||||
@@ -42,18 +42,20 @@ See the full list of everyone who made this project better in [CONTRIBUTORS.md](
|
||||
<details>
|
||||
<summary><strong>📦 Releases & Session Recovery</strong></summary>
|
||||
|
||||
### Current Version: v2.26.2
|
||||
### Current Version: v2.29.0
|
||||
|
||||
| Version | Highlights |
|
||||
|---------|------------|
|
||||
| **v2.26.2** | Fix: `---` in hook commands broke YAML frontmatter parsing — hooks now register correctly |
|
||||
| **v2.26.1** | Fix: session catchup after `/clear` — path sanitization on Windows + content injection (thanks @tony-stark-eth!) |
|
||||
| **v2.29.0** | Analytics workflow template: `--template analytics` flag for data exploration sessions (thanks @mvanhorn!) |
|
||||
| **v2.28.0** | Traditional Chinese (zh-TW) skill variant (thanks @waynelee2048!) |
|
||||
| **v2.26.2** | Fix: `---` in hook commands broke YAML frontmatter parsing, hooks now register correctly |
|
||||
| **v2.26.1** | Fix: session catchup after `/clear`, path sanitization on Windows + content injection (thanks @tony-stark-eth!) |
|
||||
| **v2.26.0** | IDE audit: Factory hooks, Copilot errorOccurred hook, Gemini hooks, bug fixes |
|
||||
| **v2.18.2** | Mastra Code hooks fix (hooks.json + docs accuracy) |
|
||||
| **v2.18.1** | Copilot garbled characters complete fix |
|
||||
| **v2.18.0** | BoxLite sandbox runtime integration |
|
||||
| **v2.17.0** | Mastra Code support + all IDE SKILL.md spec fixes |
|
||||
| **v2.16.1** | Copilot garbled characters fix — PS1 UTF-8 encoding + bash ensure_ascii (thanks @Hexiaopi!) |
|
||||
| **v2.16.1** | Copilot garbled characters fix: PS1 UTF-8 encoding + bash ensure_ascii (thanks @Hexiaopi!) |
|
||||
| **v2.16.0** | GitHub Copilot hooks support (thanks @lincolnwan!) |
|
||||
| **v2.27.0** | Kiro Agent Skill layout (thanks @EListenX!) |
|
||||
| **v2.15.1** | Session catchup false-positive fix (thanks @gydx6!) |
|
||||
@@ -102,7 +104,7 @@ These IDEs have dedicated hook configurations that automatically re-read your pl
|
||||
| Mastra Code | [Mastra Setup](docs/mastra.md) | Skills + [Hooks](https://mastra.ai/docs/mastra-code/configuration) |
|
||||
| Gemini CLI | [Gemini Setup](docs/gemini.md) | Skills + [Hooks](https://geminicli.com/docs/hooks/) |
|
||||
| Kiro | [Kiro Setup](docs/kiro.md) | [Agent Skills](https://kiro.dev/docs/skills/) |
|
||||
| Codex | [Codex Setup](docs/codex.md) | [Skills + Hooks](https://developers.openai.com/codex/skills) |
|
||||
| Codex | [Codex Setup](docs/codex.md) | [Skills + Hooks](https://developers.openai.com/codex/hooks) |
|
||||
| CodeBuddy | [CodeBuddy Setup](docs/codebuddy.md) | [Skills + Hooks](https://www.codebuddy.ai/docs/cli/skills) |
|
||||
| FactoryAI Droid | [Factory Setup](docs/factory.md) | [Skills + Hooks](https://docs.factory.ai/cli/configuration/skills) |
|
||||
| OpenCode | [OpenCode Setup](docs/opencode.md) | Skills + Custom session storage |
|
||||
@@ -152,7 +154,7 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
|
||||
[](https://docs.github.com/en/copilot/reference/hooks-configuration)
|
||||
[](https://code.mastra.ai)
|
||||
[](https://boxlite.ai)
|
||||
[](https://github.com/OthmanAdi/planning-with-files/releases)
|
||||
[](https://github.com/OthmanAdi/planning-with-files/releases)
|
||||
[](https://getskillcheck.com)
|
||||
|
||||
## Quick Install
|
||||
@@ -351,6 +353,8 @@ planning-with-files/
|
||||
│ └── skills/
|
||||
│ └── planning-with-files/
|
||||
├── .codex/ # Codex CLI skills + hooks
|
||||
│ ├── hooks.json # Hook configuration
|
||||
│ ├── hooks/ # Hook scripts + Codex adapters
|
||||
│ └── skills/
|
||||
├── .opencode/ # OpenCode skills (custom session storage)
|
||||
│ └── skills/
|
||||
|
||||
+127
-32
@@ -1,22 +1,35 @@
|
||||
# Codex IDE Support
|
||||
# Codex Setup
|
||||
|
||||
Using planning-with-files with [OpenAI Codex](https://developers.openai.com/codex/).
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
planning-with-files works with Codex as a personal skill in `~/.codex/skills/`.
|
||||
Codex discovers skills from `.codex/skills/` and hooks from `.codex/hooks.json` or `~/.codex/hooks.json`.
|
||||
|
||||
This integration includes both:
|
||||
|
||||
- `.codex/skills/planning-with-files/` for the skill itself
|
||||
- `.codex/hooks.json` plus `.codex/hooks/` for lifecycle automation
|
||||
|
||||
The hook behavior reuses the same mature shell scripts as the Cursor integration, with a thin Codex adapter layer for the differences in hook protocol.
|
||||
|
||||
> **Important:** Codex hooks require `codex_hooks = true` in `~/.codex/config.toml`.
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
Codex auto-discovers skills from `.codex/skills/` directories. Two installation methods:
|
||||
|
||||
### Method 1: Workspace Installation (Recommended)
|
||||
|
||||
Share the skill with your entire team by adding it to your repository:
|
||||
Share the skill and hooks with your whole team by committing `.codex/` to your repository:
|
||||
|
||||
```bash
|
||||
# In your project repository
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
|
||||
|
||||
# Copy the Codex skill to your repo
|
||||
# Copy the Codex integration to your repo
|
||||
cp -r /tmp/planning-with-files/.codex .
|
||||
|
||||
# Commit to share with team
|
||||
@@ -28,8 +41,6 @@ git push
|
||||
rm -rf /tmp/planning-with-files
|
||||
```
|
||||
|
||||
Now everyone on your team using Codex will have access to the skill!
|
||||
|
||||
### Method 2: Personal Installation
|
||||
|
||||
Install just for yourself:
|
||||
@@ -38,45 +49,129 @@ Install just for yourself:
|
||||
# Clone the repo
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
|
||||
|
||||
# Copy to your personal Codex skills folder
|
||||
# Copy the skill
|
||||
mkdir -p ~/.codex/skills
|
||||
cp -r /tmp/planning-with-files/.codex/skills/planning-with-files ~/.codex/skills/
|
||||
|
||||
# Copy the hook scripts
|
||||
mkdir -p ~/.codex/hooks
|
||||
cp -r /tmp/planning-with-files/.codex/hooks/* ~/.codex/hooks/
|
||||
|
||||
# Copy hooks.json
|
||||
# If you already have ~/.codex/hooks.json, merge the planning-with-files entries manually
|
||||
cp /tmp/planning-with-files/.codex/hooks.json ~/.codex/hooks.json
|
||||
|
||||
# Clean up
|
||||
rm -rf /tmp/planning-with-files
|
||||
```
|
||||
|
||||
## Usage with Superpowers
|
||||
> **Note:** If you already have a `~/.codex/hooks.json`, do not overwrite it blindly. Merge the `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` entries into your existing file.
|
||||
|
||||
If you have [obra/superpowers](https://github.com/obra/superpowers) installed:
|
||||
### Enable Hooks in `config.toml`
|
||||
|
||||
```bash
|
||||
~/.codex/superpowers/.codex/superpowers-codex use-skill planning-with-files
|
||||
Ensure your `~/.codex/config.toml` contains:
|
||||
|
||||
```toml
|
||||
[features]
|
||||
codex_hooks = true
|
||||
```
|
||||
|
||||
## Usage without Superpowers
|
||||
If you already have a `[features]` section, add `codex_hooks = true` under it instead of creating a duplicate section.
|
||||
|
||||
Add to your `~/.codex/AGENTS.md`:
|
||||
|
||||
```markdown
|
||||
## Planning with Files
|
||||
|
||||
<IMPORTANT>
|
||||
For complex tasks (3+ steps, research, projects):
|
||||
1. Read skill: `cat ~/.codex/skills/planning-with-files/SKILL.md`
|
||||
2. Create task_plan.md, findings.md, progress.md in your project directory
|
||||
3. Follow 3-file pattern throughout the task
|
||||
</IMPORTANT>
|
||||
```
|
||||
|
||||
## Verification
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
codex --version
|
||||
codex features list | rg '^codex_hooks\\s'
|
||||
ls -la ~/.codex/skills/planning-with-files/SKILL.md
|
||||
ls -la ~/.codex/hooks.json ~/.codex/hooks/
|
||||
```
|
||||
|
||||
## Learn More
|
||||
If `codex_hooks` does not appear in `codex features list`, upgrade Codex before troubleshooting the skill.
|
||||
|
||||
- [Installation Guide](installation.md)
|
||||
- [Quick Start](quickstart.md)
|
||||
- [Workflow Diagram](workflow.md)
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Hooks
|
||||
|
||||
Codex reads hooks from:
|
||||
|
||||
1. `.codex/hooks.json` in your project root
|
||||
2. `~/.codex/hooks.json` for your global install
|
||||
|
||||
This integration includes all five Codex lifecycle hooks:
|
||||
|
||||
| Hook | What It Does |
|
||||
|------|--------------|
|
||||
| **SessionStart** | Runs `session-catchup.py`, then injects active plan context |
|
||||
| **UserPromptSubmit** | Re-injects plan and recent progress on every user message |
|
||||
| **PreToolUse** | Re-reads the first 30 lines of `task_plan.md` before Bash |
|
||||
| **PostToolUse** | Reminds the agent to update `progress.md` after Bash activity |
|
||||
| **Stop** | Blocks once when phases are incomplete, then falls back to a follow-up reminder |
|
||||
|
||||
### The Three Files
|
||||
|
||||
Once activated, the skill creates and maintains:
|
||||
|
||||
| File | Purpose | Location |
|
||||
|------|---------|----------|
|
||||
| `task_plan.md` | Phases, progress, decisions | Your project root |
|
||||
| `findings.md` | Research, discoveries | Your project root |
|
||||
| `progress.md` | Session log, test results | Your project root |
|
||||
|
||||
---
|
||||
|
||||
## Team Workflow
|
||||
|
||||
### Workspace Installation
|
||||
|
||||
With workspace installation (`.codex/` committed to your repo):
|
||||
|
||||
- Everyone on the team gets the same skill and hooks
|
||||
- The Codex setup is version controlled with the project
|
||||
- Updates ship through normal git review
|
||||
|
||||
### Personal Installation
|
||||
|
||||
With personal installation (`~/.codex/`):
|
||||
|
||||
- You can use the skill across all projects
|
||||
- You keep your setup even if you change repositories
|
||||
- Existing global hooks may need manual merging
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hooks Not Running?
|
||||
|
||||
1. Check that `codex_hooks = true` is present in `~/.codex/config.toml`
|
||||
2. Verify `.codex/hooks.json` or `~/.codex/hooks.json` exists
|
||||
3. Restart Codex after adding or changing hooks
|
||||
4. Run `codex features list | rg '^codex_hooks\\s'`
|
||||
|
||||
### Already Using Other Global Hooks?
|
||||
|
||||
That is fine, but do not overwrite your existing `~/.codex/hooks.json`. Merge the planning-with-files entries instead.
|
||||
|
||||
### Seeing Duplicate Hook Messages?
|
||||
|
||||
Avoid installing the same planning-with-files hooks in both places at once:
|
||||
|
||||
- workspace `.codex/hooks.json`
|
||||
- global `~/.codex/hooks.json`
|
||||
|
||||
If you enable both, Codex may run both sets of hooks and duplicate the reminders.
|
||||
|
||||
### Windows Support
|
||||
|
||||
OpenAI's current Codex hooks documentation says hooks are disabled on Windows. The skill files can still be installed there, but the hook automation is currently for macOS/Linux Codex environments.
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
- **GitHub Issues:** https://github.com/OthmanAdi/planning-with-files/issues
|
||||
- **OpenAI Codex Hooks Docs:** https://developers.openai.com/codex/hooks
|
||||
- **OpenAI Codex Skills Docs:** https://developers.openai.com/codex/skills
|
||||
|
||||
@@ -1,17 +1,34 @@
|
||||
# Initialize planning files for a new session
|
||||
# Usage: .\init-session.ps1 [project-name]
|
||||
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
|
||||
# Templates: default, analytics
|
||||
|
||||
param(
|
||||
[string]$ProjectName = "project"
|
||||
[string]$ProjectName = "project",
|
||||
[string]$Template = "default"
|
||||
)
|
||||
|
||||
$DATE = Get-Date -Format "yyyy-MM-dd"
|
||||
|
||||
Write-Host "Initializing planning files for: $ProjectName"
|
||||
# Resolve template directory (skill root is one level up from scripts/)
|
||||
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
|
||||
$SkillRoot = Split-Path -Parent $ScriptDir
|
||||
$TemplateDir = Join-Path $SkillRoot "templates"
|
||||
|
||||
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
|
||||
|
||||
# Validate template
|
||||
if ($Template -ne "default" -and $Template -ne "analytics") {
|
||||
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
|
||||
$Template = "default"
|
||||
}
|
||||
|
||||
# Create task_plan.md if it doesn't exist
|
||||
if (-not (Test-Path "task_plan.md")) {
|
||||
@"
|
||||
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
|
||||
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
|
||||
Copy-Item $AnalyticsPlan "task_plan.md"
|
||||
} else {
|
||||
@"
|
||||
# Task Plan: [Brief Description]
|
||||
|
||||
## Goal
|
||||
@@ -56,6 +73,7 @@ Phase 1
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
|
||||
}
|
||||
Write-Host "Created task_plan.md"
|
||||
} else {
|
||||
Write-Host "task_plan.md already exists, skipping"
|
||||
@@ -63,7 +81,11 @@ Phase 1
|
||||
|
||||
# Create findings.md if it doesn't exist
|
||||
if (-not (Test-Path "findings.md")) {
|
||||
@"
|
||||
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
|
||||
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
|
||||
Copy-Item $AnalyticsFindings "findings.md"
|
||||
} else {
|
||||
@"
|
||||
# Findings & Decisions
|
||||
|
||||
## Requirements
|
||||
@@ -83,6 +105,7 @@ if (-not (Test-Path "findings.md")) {
|
||||
## Resources
|
||||
-
|
||||
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
|
||||
}
|
||||
Write-Host "Created findings.md"
|
||||
} else {
|
||||
Write-Host "findings.md already exists, skipping"
|
||||
@@ -90,7 +113,29 @@ if (-not (Test-Path "findings.md")) {
|
||||
|
||||
# Create progress.md if it doesn't exist
|
||||
if (-not (Test-Path "progress.md")) {
|
||||
@"
|
||||
if ($Template -eq "analytics") {
|
||||
@"
|
||||
# Progress Log
|
||||
|
||||
## Session: $DATE
|
||||
|
||||
### Current Status
|
||||
- **Phase:** 1 - Data Discovery
|
||||
- **Started:** $DATE
|
||||
|
||||
### Actions Taken
|
||||
-
|
||||
|
||||
### Query Log
|
||||
| Query | Result Summary | Interpretation |
|
||||
|-------|---------------|----------------|
|
||||
|
||||
### Errors
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
|
||||
} else {
|
||||
@"
|
||||
# Progress Log
|
||||
|
||||
## Session: $DATE
|
||||
@@ -110,6 +155,7 @@ if (-not (Test-Path "progress.md")) {
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
|
||||
}
|
||||
Write-Host "Created progress.md"
|
||||
} else {
|
||||
Write-Host "progress.md already exists, skipping"
|
||||
|
||||
+65
-6
@@ -1,17 +1,48 @@
|
||||
#!/bin/bash
|
||||
# Initialize planning files for a new session
|
||||
# Usage: ./init-session.sh [project-name]
|
||||
# Usage: ./init-session.sh [--template TYPE] [project-name]
|
||||
# Templates: default, analytics
|
||||
|
||||
set -e
|
||||
|
||||
PROJECT_NAME="${1:-project}"
|
||||
# Parse arguments
|
||||
TEMPLATE="default"
|
||||
PROJECT_NAME="project"
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--template|-t)
|
||||
TEMPLATE="$2"
|
||||
shift 2
|
||||
;;
|
||||
*)
|
||||
PROJECT_NAME="$1"
|
||||
shift
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
DATE=$(date +%Y-%m-%d)
|
||||
|
||||
echo "Initializing planning files for: $PROJECT_NAME"
|
||||
# Resolve template directory (skill root is one level up from scripts/)
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
|
||||
TEMPLATE_DIR="$SKILL_ROOT/templates"
|
||||
|
||||
echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
|
||||
|
||||
# Validate template
|
||||
if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
|
||||
echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
|
||||
TEMPLATE="default"
|
||||
fi
|
||||
|
||||
# Create task_plan.md if it doesn't exist
|
||||
if [ ! -f "task_plan.md" ]; then
|
||||
cat > task_plan.md << 'EOF'
|
||||
if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
|
||||
cp "$TEMPLATE_DIR/analytics_task_plan.md" task_plan.md
|
||||
else
|
||||
cat > task_plan.md << 'EOF'
|
||||
# Task Plan: [Brief Description]
|
||||
|
||||
## Goal
|
||||
@@ -56,6 +87,7 @@ Phase 1
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
EOF
|
||||
fi
|
||||
echo "Created task_plan.md"
|
||||
else
|
||||
echo "task_plan.md already exists, skipping"
|
||||
@@ -63,7 +95,10 @@ fi
|
||||
|
||||
# Create findings.md if it doesn't exist
|
||||
if [ ! -f "findings.md" ]; then
|
||||
cat > findings.md << 'EOF'
|
||||
if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
|
||||
cp "$TEMPLATE_DIR/analytics_findings.md" findings.md
|
||||
else
|
||||
cat > findings.md << 'EOF'
|
||||
# Findings & Decisions
|
||||
|
||||
## Requirements
|
||||
@@ -83,6 +118,7 @@ if [ ! -f "findings.md" ]; then
|
||||
## Resources
|
||||
-
|
||||
EOF
|
||||
fi
|
||||
echo "Created findings.md"
|
||||
else
|
||||
echo "findings.md already exists, skipping"
|
||||
@@ -90,7 +126,29 @@ fi
|
||||
|
||||
# Create progress.md if it doesn't exist
|
||||
if [ ! -f "progress.md" ]; then
|
||||
cat > progress.md << EOF
|
||||
if [ "$TEMPLATE" = "analytics" ]; then
|
||||
cat > progress.md << EOF
|
||||
# Progress Log
|
||||
|
||||
## Session: $DATE
|
||||
|
||||
### Current Status
|
||||
- **Phase:** 1 - Data Discovery
|
||||
- **Started:** $DATE
|
||||
|
||||
### Actions Taken
|
||||
-
|
||||
|
||||
### Query Log
|
||||
| Query | Result Summary | Interpretation |
|
||||
|-------|---------------|----------------|
|
||||
|
||||
### Errors
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
EOF
|
||||
else
|
||||
cat > progress.md << EOF
|
||||
# Progress Log
|
||||
|
||||
## Session: $DATE
|
||||
@@ -110,6 +168,7 @@ if [ ! -f "progress.md" ]; then
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
EOF
|
||||
fi
|
||||
echo "Created progress.md"
|
||||
else
|
||||
echo "progress.md already exists, skipping"
|
||||
|
||||
@@ -21,9 +21,9 @@ hooks:
|
||||
Stop:
|
||||
- hooks:
|
||||
- type: command
|
||||
command: "SD=\"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
|
||||
command: "SD=\"${CLAUDE_SKILL_DIR:-${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
|
||||
metadata:
|
||||
version: "2.26.1"
|
||||
version: "2.30.0"
|
||||
---
|
||||
|
||||
# Planning with Files
|
||||
@@ -39,7 +39,7 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
||||
$(command -v python3 || command -v python) ${CLAUDE_SKILL_DIR}/scripts/session-catchup.py "$(pwd)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
@@ -55,7 +55,7 @@ If catchup report shows unsynced context:
|
||||
|
||||
## Important: Where Files Go
|
||||
|
||||
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
|
||||
- **Templates** are in `${CLAUDE_SKILL_DIR}/templates/`
|
||||
- **Your planning files** go in **your project directory**
|
||||
|
||||
| Location | What Goes There |
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# Findings & Decisions
|
||||
<!--
|
||||
WHAT: Knowledge base for your analytics session. Stores data sources, hypotheses, and results.
|
||||
WHY: Context windows are limited. This file is your "external memory" for analytical work.
|
||||
WHEN: Update after ANY discovery, especially after running queries or viewing charts.
|
||||
-->
|
||||
|
||||
## Data Sources
|
||||
<!--
|
||||
WHAT: Every data source you connected to, with schema details and quality notes.
|
||||
WHY: Knowing where your data came from and its limitations is critical for reproducibility.
|
||||
EXAMPLE:
|
||||
| user_events | PostgreSQL prod replica | 2.3M rows | user_id, event_type, ts | 0.2% null user_id |
|
||||
| revenue.csv | Finance team export | 45K rows | account_id, mrr, churn_date | Complete, no nulls |
|
||||
-->
|
||||
| Source | Location | Size | Key Fields | Quality Notes |
|
||||
|--------|----------|------|------------|---------------|
|
||||
| | | | | |
|
||||
|
||||
## Hypothesis Log
|
||||
<!--
|
||||
WHAT: Each hypothesis you tested, the method used, and the result.
|
||||
WHY: Structured tracking prevents p-hacking and makes your reasoning auditable.
|
||||
EXAMPLE:
|
||||
| H1: Churn > 50% for low-activity users | Chi-squared test | Confirmed (p=0.003) | High |
|
||||
| H2: Feature X correlates with retention | Pearson correlation | Rejected (r=0.08) | High |
|
||||
-->
|
||||
| Hypothesis | Test Method | Result | Confidence |
|
||||
|------------|-------------|--------|------------|
|
||||
| | | | |
|
||||
|
||||
## Query Results
|
||||
<!--
|
||||
WHAT: Key queries you ran and what they revealed.
|
||||
WHY: Queries are ephemeral - if you don't write down the results, they're lost on context reset.
|
||||
WHEN: After EVERY significant query. Don't wait.
|
||||
EXAMPLE:
|
||||
### Churn rate by activity segment
|
||||
Query: SELECT activity_bucket, COUNT(*), AVG(churned) FROM user_segments GROUP BY 1
|
||||
Result: Low activity: 62% churn, Medium: 28%, High: 8%
|
||||
Interpretation: Strong inverse relationship between activity and churn
|
||||
-->
|
||||
<!-- Record query, result summary, and interpretation for each significant query -->
|
||||
|
||||
## Statistical Findings
|
||||
<!--
|
||||
WHAT: Formal statistical test results with all relevant metrics.
|
||||
WHY: Recording p-values, effect sizes, and confidence intervals makes results reproducible.
|
||||
EXAMPLE:
|
||||
| Chi-squared (churn ~ activity) | p=0.003 | Cramer's V=0.31 | Reject null: activity segments differ significantly in churn |
|
||||
| Pearson (feature_x ~ retention) | p=0.42 | r=0.08 | Fail to reject: no meaningful correlation |
|
||||
-->
|
||||
| Test | p-value | Effect Size | Conclusion |
|
||||
|------|---------|-------------|------------|
|
||||
| | | | |
|
||||
|
||||
## Technical Decisions
|
||||
<!--
|
||||
WHAT: Analytical method choices with reasoning.
|
||||
EXAMPLE:
|
||||
| Use log transform on revenue | Right-skewed distribution, normalizes for parametric tests |
|
||||
-->
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| | |
|
||||
|
||||
## Issues Encountered
|
||||
| Issue | Resolution |
|
||||
|-------|------------|
|
||||
| | |
|
||||
|
||||
## Resources
|
||||
<!-- URLs, file paths, documentation links -->
|
||||
-
|
||||
|
||||
## Visual/Browser Findings
|
||||
<!--
|
||||
CRITICAL: Update after viewing charts, dashboards, or browser results.
|
||||
Multimodal content doesn't persist in context - capture as text immediately.
|
||||
-->
|
||||
-
|
||||
|
||||
---
|
||||
*Update this file after every 2 view/browser/search operations*
|
||||
*This prevents visual information from being lost*
|
||||
@@ -0,0 +1,106 @@
|
||||
# Task Plan: [Analytics Project Description]
|
||||
<!--
|
||||
WHAT: Roadmap for a data analytics or exploration session.
|
||||
WHY: Analytics workflows have different phases than software development — hypothesis testing,
|
||||
data quality checks, and statistical validation don't map to a generic build cycle.
|
||||
WHEN: Create this FIRST before starting any data exploration. Update after each phase.
|
||||
-->
|
||||
|
||||
## Goal
|
||||
<!--
|
||||
WHAT: One clear sentence describing what you're trying to learn or produce.
|
||||
EXAMPLE: "Determine which user segments have the highest churn risk using last 90 days of activity data."
|
||||
-->
|
||||
[One sentence describing the analytical objective]
|
||||
|
||||
## Current Phase
|
||||
<!--
|
||||
WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3").
|
||||
WHY: Quick reference for where you are. Update this as you progress.
|
||||
-->
|
||||
Phase 1
|
||||
|
||||
## Phases
|
||||
|
||||
### Phase 1: Data Discovery
|
||||
<!--
|
||||
WHAT: Connect to data sources, understand schemas, assess data quality.
|
||||
WHY: Bad data produces bad analysis. This phase prevents wasted effort on unreliable inputs.
|
||||
-->
|
||||
- [ ] Identify and connect to data sources
|
||||
- [ ] Document schemas and field descriptions in findings.md
|
||||
- [ ] Assess data quality (nulls, duplicates, outliers, date ranges)
|
||||
- [ ] Estimate dataset size and query performance
|
||||
- **Status:** in_progress
|
||||
|
||||
### Phase 2: Exploratory Analysis
|
||||
<!--
|
||||
WHAT: Distributions, correlations, outliers, initial patterns.
|
||||
WHY: Understanding the shape of your data before testing hypotheses prevents false conclusions.
|
||||
-->
|
||||
- [ ] Compute summary statistics for key variables
|
||||
- [ ] Visualize distributions and relationships
|
||||
- [ ] Identify outliers and anomalies
|
||||
- [ ] Document initial patterns in findings.md
|
||||
- **Status:** pending
|
||||
|
||||
### Phase 3: Hypothesis Testing
|
||||
<!--
|
||||
WHAT: Formalize hypotheses, run statistical tests, validate findings.
|
||||
WHY: Moving from "it looks like X" to "we can confidently say X" requires structured testing.
|
||||
-->
|
||||
- [ ] Formalize hypotheses from exploratory phase
|
||||
- [ ] Select appropriate statistical tests
|
||||
- [ ] Run tests and record results in findings.md
|
||||
- [ ] Validate findings against holdout data or alternative methods
|
||||
- **Status:** pending
|
||||
|
||||
### Phase 4: Synthesis & Reporting
|
||||
<!--
|
||||
WHAT: Summarize findings, create visualizations, document conclusions.
|
||||
WHY: Analysis without clear communication is wasted work. This phase produces the deliverable.
|
||||
-->
|
||||
- [ ] Summarize key findings with supporting evidence
|
||||
- [ ] Create final visualizations
|
||||
- [ ] Document conclusions and recommendations
|
||||
- [ ] Note limitations and areas for further investigation
|
||||
- **Status:** pending
|
||||
|
||||
## Hypotheses
|
||||
<!--
|
||||
WHAT: Questions you're investigating, stated as testable hypotheses.
|
||||
WHY: Explicit hypotheses prevent fishing expeditions and keep analysis focused.
|
||||
EXAMPLE:
|
||||
1. Users who logged in < 3 times in the last 30 days have > 50% churn rate (H1)
|
||||
2. Feature X adoption correlates with retention (r > 0.3) (H2)
|
||||
-->
|
||||
1. [Hypothesis to test]
|
||||
2. [Hypothesis to test]
|
||||
|
||||
## Decisions Made
|
||||
<!--
|
||||
WHAT: Analytical decisions with reasoning (e.g., choosing a test, filtering criteria).
|
||||
EXAMPLE:
|
||||
| Use median instead of mean | Revenue data is heavily right-skewed |
|
||||
| Filter to last 90 days | Earlier data uses a different tracking schema |
|
||||
-->
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| | |
|
||||
|
||||
## Errors Encountered
|
||||
<!--
|
||||
WHAT: Every error you encounter, what attempt number it was, and how you resolved it.
|
||||
EXAMPLE:
|
||||
| Query timeout on raw table | 1 | Added date partition filter |
|
||||
| Null join keys in user_events | 2 | Inner join instead of left join, documented data loss |
|
||||
-->
|
||||
| Error | Attempt | Resolution |
|
||||
|-------|---------|------------|
|
||||
| | 1 | |
|
||||
|
||||
## Notes
|
||||
- Update phase status as you progress: pending -> in_progress -> complete
|
||||
- Re-read this plan before major analytical decisions
|
||||
- Log ALL errors - they help avoid repetition
|
||||
- Write query results and visual findings to findings.md immediately
|
||||
@@ -0,0 +1,151 @@
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import textwrap
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
CODEX_ROOT = REPO_ROOT / ".codex"
|
||||
HOOKS_JSON = CODEX_ROOT / "hooks.json"
|
||||
HOOKS_DIR = CODEX_ROOT / "hooks"
|
||||
|
||||
|
||||
class CodexHooksTests(unittest.TestCase):
|
||||
def run_python_hook(self, script_name: str, payload: dict, cwd: Path) -> subprocess.CompletedProcess[str]:
|
||||
return subprocess.run(
|
||||
[sys.executable, str(HOOKS_DIR / script_name)],
|
||||
input=json.dumps(payload),
|
||||
text=True,
|
||||
capture_output=True,
|
||||
cwd=str(cwd),
|
||||
check=False,
|
||||
)
|
||||
|
||||
def run_shell_hook(self, script_name: str, cwd: Path, env: dict | None = None) -> subprocess.CompletedProcess[str]:
|
||||
return subprocess.run(
|
||||
["sh", str(HOOKS_DIR / script_name)],
|
||||
text=True,
|
||||
capture_output=True,
|
||||
cwd=str(cwd),
|
||||
env=env,
|
||||
check=False,
|
||||
)
|
||||
|
||||
def test_hooks_json_declares_all_expected_codex_events(self) -> None:
|
||||
self.assertTrue(HOOKS_JSON.exists(), ".codex/hooks.json is missing")
|
||||
|
||||
payload = json.loads(HOOKS_JSON.read_text(encoding="utf-8"))
|
||||
self.assertEqual(
|
||||
{"SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"},
|
||||
set(payload["hooks"]),
|
||||
)
|
||||
|
||||
def test_session_start_reuses_plan_context(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as tmpdir, tempfile.TemporaryDirectory() as home:
|
||||
root = Path(tmpdir)
|
||||
root.joinpath("task_plan.md").write_text(
|
||||
"# Task Plan\n\n## Goal\nShip Codex hooks\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
root.joinpath("progress.md").write_text(
|
||||
"# Progress\n\nFinished adapter draft.\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
root.joinpath("findings.md").write_text(
|
||||
"# Findings\n\n- reuse cursor hooks\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
env = os.environ.copy()
|
||||
env["HOME"] = home
|
||||
result = self.run_shell_hook("session-start.sh", root, env=env)
|
||||
|
||||
self.assertEqual(0, result.returncode, result.stderr)
|
||||
self.assertIn("ACTIVE PLAN", result.stdout)
|
||||
self.assertIn("Ship Codex hooks", result.stdout)
|
||||
self.assertIn("Finished adapter draft", result.stdout)
|
||||
|
||||
def test_pre_tool_use_adapter_emits_system_message(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
root = Path(tmpdir)
|
||||
root.joinpath("task_plan.md").write_text(
|
||||
textwrap.dedent(
|
||||
"""\
|
||||
# Task Plan
|
||||
### Phase 1: Discovery
|
||||
- **Status:** complete
|
||||
"""
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
result = self.run_python_hook(
|
||||
"pre_tool_use.py",
|
||||
{"cwd": str(root), "tool_input": {"command": "pwd"}},
|
||||
root,
|
||||
)
|
||||
|
||||
self.assertEqual(0, result.returncode, result.stderr)
|
||||
payload = json.loads(result.stdout)
|
||||
self.assertIn("systemMessage", payload)
|
||||
self.assertIn("# Task Plan", payload["systemMessage"])
|
||||
|
||||
def test_post_tool_use_adapter_emits_progress_reminder(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
root = Path(tmpdir)
|
||||
root.joinpath("task_plan.md").write_text("# Task Plan\n", encoding="utf-8")
|
||||
|
||||
result = self.run_python_hook(
|
||||
"post_tool_use.py",
|
||||
{"cwd": str(root), "tool_response": "ok"},
|
||||
root,
|
||||
)
|
||||
|
||||
self.assertEqual(0, result.returncode, result.stderr)
|
||||
payload = json.loads(result.stdout)
|
||||
self.assertIn("progress.md", payload["systemMessage"])
|
||||
|
||||
def test_stop_adapter_blocks_once_then_allows_reentry(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as tmpdir:
|
||||
root = Path(tmpdir)
|
||||
root.joinpath("task_plan.md").write_text(
|
||||
textwrap.dedent(
|
||||
"""\
|
||||
### Phase 1: Discovery
|
||||
- **Status:** complete
|
||||
|
||||
### Phase 2: Implementation
|
||||
- **Status:** pending
|
||||
"""
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
first = self.run_python_hook(
|
||||
"stop.py",
|
||||
{"cwd": str(root), "stop_hook_active": False},
|
||||
root,
|
||||
)
|
||||
second = self.run_python_hook(
|
||||
"stop.py",
|
||||
{"cwd": str(root), "stop_hook_active": True},
|
||||
root,
|
||||
)
|
||||
|
||||
self.assertEqual(0, first.returncode, first.stderr)
|
||||
self.assertEqual(0, second.returncode, second.stderr)
|
||||
|
||||
first_payload = json.loads(first.stdout)
|
||||
second_payload = json.loads(second.stdout)
|
||||
|
||||
self.assertEqual("block", first_payload["decision"])
|
||||
self.assertIn("Task incomplete", first_payload["reason"])
|
||||
self.assertIn("Task incomplete", second_payload["systemMessage"])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,25 @@
|
||||
import os
|
||||
import stat
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SCRIPT_PATHS = [
|
||||
".codex/skills/planning-with-files/scripts/init-session.sh",
|
||||
".codex/skills/planning-with-files/scripts/check-complete.sh",
|
||||
".codex/skills/planning-with-files/scripts/session-catchup.py",
|
||||
]
|
||||
|
||||
|
||||
class CodexScriptPermissionTests(unittest.TestCase):
|
||||
@unittest.skipIf(os.name == "nt", "Executable mode bits are not reliable on Windows.")
|
||||
def test_codex_direct_run_scripts_are_tracked_as_executable(self) -> None:
|
||||
for path in SCRIPT_PATHS:
|
||||
with self.subTest(path=path):
|
||||
mode = (REPO_ROOT / path).stat().st_mode
|
||||
self.assertTrue(mode & stat.S_IXUSR, f"{path} is missing user execute bit")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user