Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 OthmanAdi
|
8459756b18 | ||
|
Igor Costa
|
fb8127682d | ||
|
stephen-abc
|
cc7c67c511 | ||
|
OthmanAdi
|
7eb674845a | ||
|
OthmanAdi
|
22055786df | ||
|
OthmanAdi
|
d7c805b3f7 | ||
|
OthmanAdi
|
ed46cfc18e | ||
|
OthmanAdi
|
0d028d4480 | ||
|
OthmanAdi
|
65c768dfa8 | ||
|
OthmanAdi
|
1e60b06929 | ||
|
OthmanAdi
|
5058565588 | ||
|
OthmanAdi
|
8f5a3c2e1c | ||
|
OthmanAdi
|
1f7aa0b6d1 | ||
|
shunfeng8421
|
bbedaad0d7 |
@@ -9,7 +9,7 @@
|
||||
"name": "planning-with-files",
|
||||
"source": "./",
|
||||
"description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans that survive context loss, /clear, and crashes, with an opt-in completion gate and multi-agent shared state on disk. Manus-style, installs across 60+ agents via the SKILL.md standard.",
|
||||
"version": "3.1.1"
|
||||
"version": "3.2.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "planning-with-files",
|
||||
"version": "3.1.1",
|
||||
"version": "3.2.0",
|
||||
"description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans (task_plan.md, findings.md, progress.md) that survive context loss and /clear, with an opt-in completion gate and multi-agent shared state. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard. Includes Arabic, German, Spanish, and Chinese (Simplified and Traditional).",
|
||||
"author": {
|
||||
"name": "OthmanAdi",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
|
||||
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear."
|
||||
user-invocable: true
|
||||
allowed-tools: "Read Write Edit Bash Glob Grep"
|
||||
hooks:
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
|
||||
---
|
||||
|
||||
@@ -41,8 +41,9 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
|
||||
**Before starting work**, check for unsynced context from a previous session:
|
||||
|
||||
```bash
|
||||
# Linux/macOS (auto-detects python3 or python)
|
||||
$(command -v python3 || command -v python) ${CODEBUDDY_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
||||
# Linux/macOS — auto-detects skill directory (plugin env or default install path)
|
||||
SKILL_DIR="${CODEBUDDY_PLUGIN_ROOT:-$HOME/.codebuddy/skills/planning-with-files}"
|
||||
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
|
||||
@@ -73,6 +73,13 @@ $COMPLETE = [Math]::Max($completePrimary, $completeInline)
|
||||
$IN_PROGRESS = [Math]::Max($inProgressPrimary, $inProgressInline)
|
||||
$PENDING = [Math]::Max($pendingPrimary, $pendingInline)
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if ($TOTAL -eq 0) {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# advisory_report: the v2.43 status echo.
|
||||
function Write-AdvisoryReport {
|
||||
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
|
||||
|
||||
@@ -97,6 +97,13 @@ if [ "$PENDING_INLINE" -gt "$PENDING_PRIMARY" ]; then PENDING="$PENDING_INLINE";
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
|
||||
advisory_report() {
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
|
||||
@@ -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
|
||||
@@ -25,6 +25,12 @@ fi
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: a task_plan.md with no "### Phase" headings is not phase-structured.
|
||||
# Without this guard the hook emits a false "0/0 phases complete" followup_message.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
|
||||
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear."
|
||||
user-invocable: true
|
||||
allowed-tools: "Read Write Edit Bash Glob Grep"
|
||||
hooks:
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -73,6 +73,13 @@ $COMPLETE = [Math]::Max($completePrimary, $completeInline)
|
||||
$IN_PROGRESS = [Math]::Max($inProgressPrimary, $inProgressInline)
|
||||
$PENDING = [Math]::Max($pendingPrimary, $pendingInline)
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if ($TOTAL -eq 0) {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# advisory_report: the v2.43 status echo.
|
||||
function Write-AdvisoryReport {
|
||||
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
|
||||
|
||||
@@ -97,6 +97,13 @@ if [ "$PENDING_INLINE" -gt "$PENDING_PRIMARY" ]; then PENDING="$PENDING_INLINE";
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
|
||||
advisory_report() {
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
|
||||
@@ -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
|
||||
@@ -73,6 +73,13 @@ $COMPLETE = [Math]::Max($completePrimary, $completeInline)
|
||||
$IN_PROGRESS = [Math]::Max($inProgressPrimary, $inProgressInline)
|
||||
$PENDING = [Math]::Max($pendingPrimary, $pendingInline)
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if ($TOTAL -eq 0) {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# advisory_report: the v2.43 status echo.
|
||||
function Write-AdvisoryReport {
|
||||
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
|
||||
|
||||
@@ -97,6 +97,13 @@ if [ "$PENDING_INLINE" -gt "$PENDING_PRIMARY" ]; then PENDING="$PENDING_INLINE";
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
|
||||
advisory_report() {
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
|
||||
@@ -32,6 +32,12 @@ fi
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not phase-structured. Avoid the false
|
||||
# "0/0 phases done ... continue working" auto-continue message.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
# All phases complete — provide re-entry guidance
|
||||
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.\"}"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
|
||||
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear."
|
||||
user-invocable: true
|
||||
allowed-tools: "Read Write Edit Bash Glob Grep"
|
||||
hooks:
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
|
||||
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear."
|
||||
user-invocable: true
|
||||
allowed-tools: "Read Write Edit Bash Glob Grep"
|
||||
hooks:
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
---
|
||||
|
||||
# Planning with Files
|
||||
|
||||
@@ -73,6 +73,13 @@ $COMPLETE = [Math]::Max($completePrimary, $completeInline)
|
||||
$IN_PROGRESS = [Math]::Max($inProgressPrimary, $inProgressInline)
|
||||
$PENDING = [Math]::Max($pendingPrimary, $pendingInline)
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if ($TOTAL -eq 0) {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# advisory_report: the v2.43 status echo.
|
||||
function Write-AdvisoryReport {
|
||||
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
|
||||
|
||||
@@ -97,6 +97,13 @@ if [ "$PENDING_INLINE" -gt "$PENDING_PRIMARY" ]; then PENDING="$PENDING_INLINE";
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
|
||||
advisory_report() {
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
|
||||
@@ -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
|
||||
@@ -73,6 +73,13 @@ $COMPLETE = [Math]::Max($completePrimary, $completeInline)
|
||||
$IN_PROGRESS = [Math]::Max($inProgressPrimary, $inProgressInline)
|
||||
$PENDING = [Math]::Max($pendingPrimary, $pendingInline)
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if ($TOTAL -eq 0) {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# advisory_report: the v2.43 status echo.
|
||||
function Write-AdvisoryReport {
|
||||
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
|
||||
|
||||
@@ -97,6 +97,13 @@ if [ "$PENDING_INLINE" -gt "$PENDING_PRIMARY" ]; then PENDING="$PENDING_INLINE";
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
|
||||
advisory_report() {
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
|
||||
@@ -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
|
||||
@@ -35,6 +35,13 @@ fi
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not phase-structured. Emit empty JSON
|
||||
# instead of a false "0/0 phases done" additionalContext.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
echo '{}'
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
MSG="[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
|
||||
echo "{\"hookSpecificOutput\":{\"hookEventName\":\"AgentStop\",\"additionalContext\":\"$MSG\"}}"
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Hermes adaptation with minimal notes.
|
||||
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Hermes adaptation with minimal notes."
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
---
|
||||
|
||||
> Hermes note: lifecycle automation for this skill is provided by the Hermes adapter plugin in `.hermes/plugins/planning-with-files/`.
|
||||
@@ -19,13 +19,15 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
|
||||
2. Then check for unsynced context from a previous session:
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
$(command -v python3 || command -v python) "$HERMES_HOME/skills/planning-with-files/scripts/session-catchup.py" "$(pwd)"
|
||||
# Linux/macOS — auto-detects skill directory (Hermes env or default install path)
|
||||
SKILL_DIR="${HERMES_HOME:-$HOME/.hermes}/skills/planning-with-files"
|
||||
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Windows PowerShell
|
||||
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:HERMES_HOME\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
|
||||
$HermesDir = if ($env:HERMES_HOME) { $env:HERMES_HOME } else { "$env:USERPROFILE\.hermes" }
|
||||
& (Get-Command python -ErrorAction SilentlyContinue).Source "$HermesDir\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
|
||||
```
|
||||
|
||||
If catchup report shows unsynced context:
|
||||
|
||||
@@ -25,6 +25,11 @@ fi
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: TOTAL=0 -> not phase-structured, stay silent
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL)."
|
||||
else
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
|
||||
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear."
|
||||
user-invocable: true
|
||||
allowed-tools: "Read Write Edit Bash Glob Grep"
|
||||
hooks:
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
|
||||
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear."
|
||||
user-invocable: true
|
||||
allowed-tools: "Read Write Edit Bash Glob Grep"
|
||||
hooks:
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -73,6 +73,13 @@ $COMPLETE = [Math]::Max($completePrimary, $completeInline)
|
||||
$IN_PROGRESS = [Math]::Max($inProgressPrimary, $inProgressInline)
|
||||
$PENDING = [Math]::Max($pendingPrimary, $pendingInline)
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if ($TOTAL -eq 0) {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# advisory_report: the v2.43 status echo.
|
||||
function Write-AdvisoryReport {
|
||||
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
|
||||
|
||||
@@ -97,6 +97,13 @@ if [ "$PENDING_INLINE" -gt "$PENDING_PRIMARY" ]; then PENDING="$PENDING_INLINE";
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
|
||||
advisory_report() {
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
|
||||
@@ -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
|
||||
@@ -6,9 +6,9 @@ This file is the canonical, session-portable reference for how every agent worki
|
||||
|
||||
## Commit rules
|
||||
|
||||
- **Author**: OthmanAdi only. NEVER add `Co-Authored-By:` trailers.
|
||||
- **Author**: OthmanAdi only for release/maintenance commits. NEVER add `Co-Authored-By:` trailers.
|
||||
- **Format**: Conventional Commits — `fix:`, `feat:`, `release:`, `docs:` prefixes.
|
||||
- **One squashed commit per release or PR merge.**
|
||||
- **One release commit on top of the contributor commit(s), never a squash of the contributor's work.** `git merge --squash` rewrites the committer as whoever runs the local commit, which reassigns the contributor's authorship to OthmanAdi — this happened once (v2.40.1 cycle) and is exactly what this rule exists to prevent. Squashing is fine only for collapsing your OWN WIP commits before pushing.
|
||||
- No `--no-verify`. No force push to master except tag ref updates.
|
||||
- Contributors are credited in CHANGELOG `### Thanks` and `CONTRIBUTORS.md`, never in commit trailers.
|
||||
|
||||
@@ -19,7 +19,7 @@ This file is the canonical, session-portable reference for how every agent worki
|
||||
1. `gh issue view N` and `gh pr view N` — read both in full.
|
||||
2. Verify the bug is real: find the exact file/line, grep for the pattern, confirm reporter is correct.
|
||||
3. `python -m pytest tests/ -q` — all tests pass before touching anything.
|
||||
4. Squash merge: `git fetch origin branch && git merge --squash origin/branch`, then a single commit as OthmanAdi.
|
||||
4. Merge preserving contributor authorship: `git fetch origin pull/N/head:pr-N && git cherry-pick <pr-head-sha>`, or `gh pr merge --rebase`. Do NOT use `git merge --squash` — it collapses the contributor's commit and reassigns the `Author:` field to whoever runs the local commit, destroying their credit in `git log`.
|
||||
5. CHANGELOG — new version entry at top, `### Fixed`/`### Added`/`### Changed`, sachlich, no em-dashes.
|
||||
6. CONTRIBUTORS.md — add reporter/contributor, bump "Total Contributors: N+", update "Last updated" date.
|
||||
7. Version bump across all 19 files (see table below).
|
||||
@@ -57,7 +57,12 @@ All 19 files must be bumped to the same version string every release.
|
||||
| `.claude-plugin/marketplace.json` | Marketplace metadata |
|
||||
| `CITATION.cff` | Citation file |
|
||||
|
||||
**NOT bumped automatically**: `.continue/`, `.gemini/` — intentionally behind. Do not bump without an explicit scope decision.
|
||||
**NOT bumped automatically**: `scripts/bump-version.py`'s `LAGGING_FILES` list currently excludes four files, not two — this table only tracked two until this correction:
|
||||
- `.continue/skills/planning-with-files/SKILL.md`, `.gemini/skills/planning-with-files/SKILL.md` — intentionally behind. Do not bump without an explicit scope decision.
|
||||
- `.pi/skills/planning-with-files/SKILL.md` — carries its own npm package version (`@tomxprime/planning-with-files`), not the canonical `metadata.version` field the parity set shares.
|
||||
- `.kiro/skills/planning-with-files/SKILL.md` — carries its own `-kiro`-suffixed scheme (e.g. `3.0.0-kiro`), bumped on Kiro-relevant changes rather than every canonical release.
|
||||
|
||||
Recent CHANGELOG entries (v3.1.1–v3.1.3) already describe this 4-file exclusion as "per AGENTS.md release scope" — this section previously did not actually say so. It does now.
|
||||
|
||||
---
|
||||
|
||||
@@ -145,7 +150,8 @@ Thanks: @handle for reporting issue #N.
|
||||
## Quick reference: what NOT to do
|
||||
|
||||
- Do not add Co-Authored-By to any commit.
|
||||
- Do not bump .continue or .gemini without explicit instruction.
|
||||
- Do not bump .continue or .gemini without explicit instruction. .pi and .kiro track their own version schemes and are never bumped by `scripts/bump-version.py`.
|
||||
- Do not `git merge --squash` a contributor PR — it reassigns their commit authorship. Use cherry-pick or `gh pr merge --rebase`.
|
||||
- Do not edit `task_plan.md` or `DESIGN.md` directly (user-owned contracts).
|
||||
- Do not log subagent returns into `task_plan.md` — use `progress.md`.
|
||||
- Do not use em-dashes in any user-facing prose.
|
||||
|
||||
@@ -2,6 +2,93 @@
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
## [3.2.0] - 2026-07-03
|
||||
|
||||
A repository health audit covering the v3 long-running-session mechanism, the
|
||||
open issue backlog, and two community pull requests. The headline finding:
|
||||
`session-catchup.py`, the mechanism behind "resume after /clear," did nothing
|
||||
on Windows. Both that and a related silent-injection bug are fixed here,
|
||||
along with the false "0/0 phases" status reported in #191.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`session-catchup.py` was non-functional on Windows** (the "resume after /clear" feature). `get_project_dir_claude` only replaced forward slashes, so a Windows-style path (`C:\Users\...` or Git Bash's `/c/Users/...`) never sanitized to Claude's actual project-directory name, and the function always returned early with no output and no error. Three `open()` calls also had no explicit encoding, so a session log containing any non-ASCII text raised `UnicodeDecodeError` on Windows' default `cp1252` codec, an error the surrounding `except` clauses swallowed silently. Fixed by detecting Windows-shaped paths before sanitizing and adding `encoding='utf-8', errors='replace'` to the three reads; genuine Unix absolute paths take the same code path as before. `tests/test_path_fix.py` previously reimplemented the sanitizer instead of importing the real module, so the suite stayed green while the shipped script stayed broken; it now imports and exercises the actual function.
|
||||
- **`inject-plan.sh`'s containment guard silently dropped plan injection and tamper detection under aliased paths.** `is_within_root()` canonicalized the project root from the `$PWD` string but canonicalized candidates from a relative path, and on a Windows account with an 8.3 short-name `TEMP` (or any path reached through the MSYS `/tmp` mount), the two resolve to differently-spelled versions of the same directory. The prefix-match check then failed and the hook exited with zero output: no plan re-injection, no tamper warning, nothing visible. Fixed by canonicalizing the root the same way candidates already are.
|
||||
- **Task plans without `### Phase` headings falsely reported "0/0 phases complete"** (#191, reported by @mixian939 against Codex). `check-complete.sh`/`.ps1` and several IDE-specific Stop hooks counted `### Phase` headings but never checked whether the count was zero before reporting a status, so an unstructured `task_plan.md` produced a false "Task in progress (0/0 phases complete)" message, or in Cursor and GitHub Copilot's adapters an auto-continue nudge to keep working on a plan that was never structured to begin with. Fixed with a `TOTAL=0` guard everywhere the pattern appeared: the canonical Claude Code scripts, `.codex`, `.cursor`, GitHub Copilot's `agent-stop.sh`, all `sync-ide-folders.py`-managed IDE mirrors, the five language-variant skills, and the standalone `.kiro` copy.
|
||||
- **`--template analytics` silently produced the default templates instead of the analytics-specific ones** (addresses #103). `templates/analytics_task_plan.md` and `templates/analytics_findings.md` (added v2.29.0) were never copied into `skills/planning-with-files/templates/`, the directory the installed skill package actually reads, so every plugin or skill-only install fell back to the generic templates. Copied both files into the canonical templates directory and added them to `sync-ide-folders.py`'s sync list, backfilling seven IDE mirrors.
|
||||
- **Windows test suite encoding errors and stale installation docs** (PR #187 by @Stephen-abc). `subprocess.run`/`Popen` calls across 15 test files had no explicit encoding, which raises `UnicodeDecodeError` on Windows accounts whose default codepage isn't UTF-8. `docs/adal.md`, `docs/antigravity.md`, `docs/kilocode.md`, and `docs/openclaw.md` also referenced `.adal/`, `.agent/`, and `.kilocode/` source paths removed in v2.24.0, and antigravity.md's templates were mislabeled as living in `references/` instead of `templates/`. Fixed the same mislabel in `docs/codebuddy.md`, which was outside PR #187's scope.
|
||||
- **Hermes adapter test failed on Windows accounts with an 8.3-short-name `TEMP`.** The test compared a `Path.resolve()`-canonicalized production result against an unresolved expected path, so accounts where `TEMP` itself resolves to a short-name alias (`OASRVA~1` vs the real account name) failed a test that was actually passing correctly. Resolved the expected side the same way.
|
||||
- **`AGENTS.md` told agents to squash-merge contributor PRs.** `git merge --squash` reassigns the contributor's commit authorship to whoever runs the local commit: the exact mistake this project's release protocol already exists to prevent (v2.40.1 cycle). Replaced with cherry-pick / `gh pr merge --rebase` guidance, matching CLAUDE.md. Also documented that `.pi` and `.kiro` lag the parity-locked version bump alongside `.continue` and `.gemini`, which recent CHANGELOG entries already assumed AGENTS.md said.
|
||||
|
||||
### Added
|
||||
|
||||
- **`docs/autohand.md`** (PR #192 by @igorcosta): setup guide for Autohand Code, added to the supported-IDEs table (18+ platforms).
|
||||
- **`SECURITY.md`** and GitHub private vulnerability reporting enabled (closes #188, requested by @AvitalAviv).
|
||||
|
||||
### Changed
|
||||
|
||||
- Version bumped to 3.2.0 across the 17 parity-locked files via `scripts/bump-version.py`. `.continue`, `.gemini`, `.pi`, and `.kiro` lag intentionally, now documented in AGENTS.md itself.
|
||||
|
||||
### Verification
|
||||
|
||||
- Python suite: 186 passed, 5 skipped, 0 failed (up from 184/4/0; two new path-sanitizer tests in `test_path_fix.py`).
|
||||
- `scripts/sync-ide-folders.py --verify`: all IDE folders in sync.
|
||||
- Functionally re-verified the long-running-session mechanism end to end on Windows after the fixes: init, check-complete, attestation lock/tamper-detect/clear, parallel-plan resolution, and session-catchup all confirmed working in both sh and PowerShell.
|
||||
- Supply-chain review on both merged PRs: docs and test files only, no dependency, install script, or bin shim in either.
|
||||
|
||||
### Thanks
|
||||
|
||||
- @mixian939 for the detailed #191 report and root-cause diagnosis against Codex, which led to finding and fixing the same defect in the canonical scripts and two other IDE adapters.
|
||||
- @Stephen-abc (Wang Jun) for the Windows test encoding fix and installation doc corrections (PR #187).
|
||||
- @igorcosta (Igor Costa, Autohand) for the Autohand Code setup docs (PR #192).
|
||||
- @AvitalAviv for flagging the missing private vulnerability disclosure channel (#188).
|
||||
- @mvanhorn for the original analytics templates (v2.29.0, #103) that this release finally ships into the installed skill package.
|
||||
|
||||
## [3.1.3] - 2026-06-16
|
||||
|
||||
A hotfix for a frontmatter regression introduced in v3.1.2. The refreshed description shipped in v3.1.2 contains a colon, and the English SKILL.md carry the `description` field unquoted, so the frontmatter became invalid YAML. This release quotes the description and adds a test that validates every SKILL.md frontmatter as YAML, so the class cannot ship again.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **SKILL.md frontmatter was invalid YAML in v3.1.2** (regression from the v3.1.2 description refresh). The new description "Manus-style persistent file-based planning for AI coding agents: keeps ..." contains a colon followed by a space. The English SKILL.md carry `description` unquoted, so a YAML loader reads the `: ` as a nested mapping and rejects the frontmatter with "mapping values are not allowed here". This affected the canonical file and the seven English IDE variants (`.codebuddy`, `.codex`, `.cursor`, `.factory`, `.hermes`, `.mastracode`, `.opencode`) and could break skill loading and the model-triggering description field. The description is now wrapped in double quotes, matching the already-quoted translated variants. The parsed value is identical, so model triggering is unchanged. The `clawhub-upload` staging bundle was corrected the same way.
|
||||
|
||||
### Added
|
||||
|
||||
- **Frontmatter validation test** (`tests/test_skill_frontmatter_valid.py`): loads every `SKILL.md` frontmatter as YAML and asserts a non-empty string description, plus a dependency-free check that no unquoted description contains `: `. The version-parity check is a regex and could not catch this regression.
|
||||
|
||||
### Changed
|
||||
|
||||
- Version bumped to 3.1.3 across the 17 parity-locked files via `scripts/bump-version.py`. `.continue`, `.gemini`, `.pi`, and `.kiro` lag intentionally per AGENTS.md release scope.
|
||||
|
||||
### Verification
|
||||
|
||||
- Python suite: 184 passed, 4 skipped, 0 failed, up from 180 with the four new frontmatter assertions.
|
||||
- Every SKILL.md in the repo, including the translated variants and the lagging `.continue`, `.gemini`, `.pi`, and `.kiro` variants, parses as valid YAML.
|
||||
|
||||
## [3.1.2] - 2026-06-16
|
||||
|
||||
A documentation patch. The session-catchup command in the skill body assumed the plugin runtime had set `${CLAUDE_PLUGIN_ROOT}`, so a skill-only install that ran the documented command in a normal shell got an empty variable and a broken path. This release adds a fallback across the affected variants, fixes the same class of bug in the `.hermes` variant, and refreshes the skill description to lead with the current positioning.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Session-catchup command works outside the plugin runtime** (PR #186 by @shunfeng8421, closes #185). The documented Restore Context command ran `${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py`, but `CLAUDE_PLUGIN_ROOT` is only set when the plugin runtime executes a hook, not in an interactive shell. A skill-only install (via `npx skills add`, or on Codex or Cursor) collapsed the command to an absolute `/scripts/...` path that does not exist. The fix uses `SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"`, so plugin users keep the variable and skill-only users fall back to the default install path. Applied to the canonical file, the `.codebuddy` variant (with its own `${CODEBUDDY_PLUGIN_ROOT}`), and the five language variants. The Windows PowerShell block and plugin behavior are unchanged.
|
||||
- **`.hermes` variant carried the same unset-variable bug** (maintainer follow-up to #186). `.hermes` used `$HERMES_HOME` in bash and `$env:HERMES_HOME` in PowerShell with no fallback, so its catchup command failed the same way outside the Hermes runtime. Both blocks now fall back to `$HOME/.hermes` and `$env:USERPROFILE\.hermes` while keeping the runtime variable as the priority.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Skill description refreshed for discoverability.** The eight English SKILL.md files (canonical plus the `.codebuddy`, `.codex`, `.cursor`, `.factory`, `.hermes`, `.mastracode`, `.opencode` adapters) now lead with "persistent file-based planning for AI coding agents" and name context-loss survival explicitly. The `Use when` trigger clause is unchanged, so model invocation behavior is identical. The five translated variants keep their localized descriptions.
|
||||
- Version bumped to 3.1.2 across the 17 parity-locked files via `scripts/bump-version.py`. `.continue`, `.gemini`, `.pi`, and `.kiro` lag intentionally per AGENTS.md release scope.
|
||||
|
||||
### Verification
|
||||
|
||||
- Python suite: 180 passed, 4 skipped, 0 failed, unchanged. The change is documentation prose with no test dependency.
|
||||
- Supply-chain review: the changed files are SKILL.md documentation only. No dependency, install hook, bin shim, or new install-path file. PR #186's diff was reviewed line by line before adoption.
|
||||
|
||||
### Thanks
|
||||
|
||||
- @shunfeng8421 for the session-catchup fallback fix (PR #186), which resolves the #185 report.
|
||||
- @xwang118 for surfacing the underlying problem in PR #183 that became #185.
|
||||
|
||||
## [3.1.1] - 2026-06-15
|
||||
|
||||
A documentation-only patch. The Codex verification command in `docs/codex.md` checked for a feature-flag name that current Codex no longer prints, so a correctly configured user running the documented check was told to upgrade. This release fixes the command and its follow-up sentence to match the canonical `hooks` flag already documented elsewhere in the same file. No code, hook, script, or test changed; the parity set is bumped to 3.1.1.
|
||||
|
||||
+2
-2
@@ -7,8 +7,8 @@ authors:
|
||||
- family-names: Adi
|
||||
given-names: Ahmad Othman Ammar
|
||||
alias: OthmanAdi
|
||||
version: "3.1.1"
|
||||
date-released: "2026-06-15"
|
||||
version: "3.2.0"
|
||||
date-released: "2026-06-16"
|
||||
license: MIT
|
||||
url: "https://github.com/OthmanAdi/planning-with-files"
|
||||
repository-code: "https://github.com/OthmanAdi/planning-with-files"
|
||||
|
||||
+19
-2
@@ -121,6 +121,11 @@ These amazing people have contributed code, documentation, or significant improv
|
||||
- The bare pattern stopped matching once Codex moved its canonical feature key from `codex_hooks` to `hooks` in 0.129.0 (openai/codex#20522); the alias still resolves in `config.toml`, but `codex features list` prints only the canonical `hooks`, so the verify step was telling correctly configured users to upgrade
|
||||
- **Impact:** the documented verification command matches on current Codex versions again, and `docs/codex.md` is internally consistent across the six places that reference the feature flag
|
||||
|
||||
- **[@shunfeng8421](https://github.com/shunfeng8421)** - [PR #186](https://github.com/OthmanAdi/planning-with-files/pull/186), [Issue #185](https://github.com/OthmanAdi/planning-with-files/issues/185)
|
||||
- Fixed the session-catchup command for skill-only installs: the documented Restore Context command used `${CLAUDE_PLUGIN_ROOT}`, which the plugin runtime sets only inside hook execution, so a user who installed via `npx skills add` or on Codex or Cursor and ran it in a normal shell got an empty variable and a broken `/scripts/...` path
|
||||
- Switched to `SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"` across the canonical file, the `.codebuddy` variant, and the five language variants, keeping the plugin path as priority and the Windows PowerShell block unchanged
|
||||
- **Impact:** skill-only installs can run the documented catchup command and get a working path, with no behavior change for plugin users. The same fallback was extended to the `.hermes` variant in the release commit. The underlying problem was surfaced by @xwang118 in PR #183 and tracked in #185
|
||||
|
||||
- **[@Skulli485](https://github.com/Skulli485)** - [PR #171](https://github.com/OthmanAdi/planning-with-files/pull/171), [Issue #162](https://github.com/OthmanAdi/planning-with-files/issues/162)
|
||||
- Authored the first `CONTRIBUTING.md` at the repo root, covering local setup, project layout, PR submission conventions, authorship and credit policy, language variant contribution rules, and where to ask questions
|
||||
- A pre-merge follow-up commit by the maintainer removed a duplicated intro and a broken four-backtick code fence from the original diff
|
||||
@@ -270,6 +275,16 @@ These amazing people have contributed code, documentation, or significant improv
|
||||
- Linked the upstream OpenAI page so the canonical key change was easy to verify
|
||||
- **Impact:** v2.39.0 swaps the docs to `hooks = true` in four sites with an alias note, so new users get the canonical key while users on older configs are not pushed to migrate
|
||||
|
||||
- **[@Stephen-abc](https://github.com/Stephen-abc)** (Wang Jun) - [PR #187](https://github.com/OthmanAdi/planning-with-files/pull/187)
|
||||
- Fixed `UnicodeDecodeError` across 15 test files by adding explicit `encoding="utf-8"` to `subprocess.run`/`Popen` calls, which fail on Windows accounts whose default codepage isn't UTF-8
|
||||
- Corrected `docs/adal.md`, `docs/antigravity.md`, `docs/kilocode.md`, and `docs/openclaw.md`, which referenced IDE-specific source folders (`.adal/`, `.agent/`, `.kilocode/`) removed in v2.24.0, and fixed a `references/` versus `templates/` mislabel in antigravity.md
|
||||
- **Impact:** v3.2.0 test suite is now robust on non-UTF-8-default Windows accounts, and four installation guides point at paths that actually exist
|
||||
|
||||
- **[@igorcosta](https://github.com/igorcosta)** (Igor Costa, Autohand) - [PR #192](https://github.com/OthmanAdi/planning-with-files/pull/192)
|
||||
- Added `docs/autohand.md`, a setup guide for Autohand Code covering user-level and project-level Agent Skills installs
|
||||
- Added Autohand Code to the README's supported-IDEs table
|
||||
- **Impact:** planning-with-files now documents a supported install path for Autohand Code alongside the other 17+ platforms
|
||||
|
||||
## Community Forks
|
||||
|
||||
These developers have created forks that extend the functionality:
|
||||
@@ -294,6 +309,8 @@ Thank you to everyone who reported issues, provided feedback, and helped test fi
|
||||
- [@st01cs](https://github.com/st01cs) - Issue #28 (Devis fork discussion)
|
||||
- [@wqh17101](https://github.com/wqh17101) - Issue #11 testing and confirmation
|
||||
- [@luyanfeng](https://github.com/luyanfeng) - Issue #172 (OpenCode install/verify paths doubled the folder segment in docs/opencode.md; fixed in v2.43.0)
|
||||
- [@mixian939](https://github.com/mixian939) - Issue #191 (Codex hooks reporting a false "0/0 phases complete" status for an unstructured task_plan.md, with a full root-cause diagnosis and suggested fix; the audit this triggered found and fixed the same defect in the canonical scripts and two other IDE adapters, fixed in v3.2.0)
|
||||
- [@AvitalAviv](https://github.com/AvitalAviv) - Issue #188 (flagged that the repo had no private vulnerability disclosure channel; private vulnerability reporting is now enabled and documented in SECURITY.md)
|
||||
|
||||
And many others who have starred, forked, and shared this project!
|
||||
|
||||
@@ -321,6 +338,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
|
||||
|
||||
---
|
||||
|
||||
**Total Contributors:** 46+ and growing!
|
||||
**Total Contributors:** 50+ and growing!
|
||||
|
||||
*Last updated: June 13, 2026*
|
||||
*Last updated: July 3, 2026*
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
[](https://skillsplayground.com/skills/othmanadi-planning-with-files-planning-with-files/)
|
||||
[](https://skill-history.com/othmanadi/planning-with-files)
|
||||
[](https://github.com/OthmanAdi/planning-with-files/releases)
|
||||
[](https://github.com/OthmanAdi/planning-with-files/releases)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/OthmanAdi/planning-with-files/issues?q=is%3Aissue+is%3Aclosed)
|
||||
[](https://github.com/OthmanAdi/planning-with-files/pulls?q=is%3Apr+is%3Aclosed)
|
||||
@@ -73,10 +73,13 @@ See the full list of everyone who made this project better in [CONTRIBUTORS.md](
|
||||
<details>
|
||||
<summary><strong>📦 Releases & Session Recovery</strong></summary>
|
||||
|
||||
### Current Version: v3.1.1
|
||||
### Current Version: v3.2.0
|
||||
|
||||
| Version | Highlights |
|
||||
|---------|------------|
|
||||
| **v3.2.0** | **Repository health audit: session-catchup.py was non-functional on Windows, plus the "0/0 phases" false status (closes #191, addresses #103, closes #188).** `session-catchup.py`, the mechanism behind "resume after `/clear`," never sanitized Windows-style paths correctly and had no explicit encoding on three reads, so it silently did nothing on Windows with no error. `inject-plan.sh`'s containment guard also silently dropped plan injection and tamper detection under 8.3 short-name or `/tmp`-aliased paths. Both fixed. Separately, `check-complete.sh`/`.ps1` and three IDE-specific Stop hooks reported a false "0/0 phases complete" for any `task_plan.md` without `### Phase` headings (#191, reported by @mixian939); fixed everywhere the pattern appeared, canonical scripts included. The `--template analytics` flag (v2.29.0) was silently falling back to default templates in every installed skill package; the analytics templates now actually ship where `init-session.sh` reads them. Merged PR #187 (@Stephen-abc: Windows test-encoding fixes, stale install-path docs) and PR #192 (@igorcosta: Autohand Code setup docs). Added `SECURITY.md` and enabled private vulnerability reporting (@AvitalAviv). Corrected `AGENTS.md`'s contributor-PR-merge guidance, which told agents to squash-merge in a way that reassigns authorship. Suite at 186 passed, 5 skipped, 0 failed. |
|
||||
| **v3.1.3** | **Hotfix: SKILL.md frontmatter was invalid YAML in v3.1.2.** The v3.1.2 description refresh added a colon, and the English SKILL.md keep `description` unquoted, so YAML rejected the frontmatter ("mapping values are not allowed here"), which could break skill loading and the model-triggering description. v3.1.3 quotes the description (matching the already-quoted translated variants; the parsed value is identical) across the canonical file and the seven English IDE variants, and adds `tests/test_skill_frontmatter_valid.py` to validate every SKILL.md frontmatter as YAML. Suite at 184 passed. |
|
||||
| **v3.1.2** | **Session-catchup command works outside the plugin runtime, `.hermes` parity, refreshed skill description** (PR #186 by @shunfeng8421 closes #185, reported by @xwang118). The documented Restore Context command used `${CLAUDE_PLUGIN_ROOT}`, which the plugin runtime sets only inside hook execution, so a skill-only install (`npx skills add`, Codex, Cursor) running it in a shell got an empty variable and a broken `/scripts/...` path. Now `SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"` on the canonical file, `.codebuddy`, and the five language variants; the `.hermes` variant got the same fallback for `$HERMES_HOME`. The eight English SKILL.md descriptions were refreshed to lead with planning for AI coding agents and context-loss survival, with the `Use when` trigger and translated variants unchanged. Documentation only; suite at 180 passed. |
|
||||
| **v3.1.1** | **Codex verification command checks the canonical `hooks` feature flag** (PR #184 by @Fat-Jan). The `docs/codex.md` verify block ran `codex features list \| rg '^codex_hooks\s'`, but Codex moved its canonical feature key from `codex_hooks` to `hooks` in 0.129.0 (openai/codex#20522). The alias still resolves in config, yet `codex features list` prints only `hooks`, so the old pattern matched nothing on current Codex and routed correctly configured users to the upgrade path. The command now greps `^(hooks\|codex_hooks)\s` and the troubleshooting sentence covers both names, matching the `hooks = true` guidance carried in the file since v2.39.0. Documentation only; suite at 180 passed. |
|
||||
| **v3.1.0** | **Codex Stop hook no longer blocks on an incomplete plan, native Codex PreCompact parity, Pi extension test suite, and accurate SHA-cache docs** (PR #180 by @2023Anita closes #178, PR #181 by @GongYuanCaiJi, PR #175 and PR #174 by @mvanhorn close #163 and #164). The `.codex` Stop adapter dropped the `{"decision":"block"}` path that pushed Codex agents to auto-continue unfinished phases; it now emits an advisory progress-sync reminder only, matching the v3 principle that an incomplete plan alone never blocks a stop. The native `.codex/hooks.json` route gained the PreCompact hook (`pre-compact.sh`) it was missing relative to the canonical SKILL.md, dormant on runtimes that never fire the event. The Pi extension gained a TypeScript integration suite covering all eight lifecycle handlers, the four runtime modes, and the attestation gate. `docs/perf-notes.md` documents the attestation SHA cache, corrected to the v3 `$XDG_CACHE_HOME/pwf-sha` location. Suite at 180 passed. |
|
||||
| **v3.0.0** | **Autonomous and gated modes for long-running agentic runs, structured run ledger, opt-in completion gate** (no breaking changes: with no mode marker the hooks produce byte-identical v2.43 output). `init-session --autonomous` drops the per-tool-call plan re-injection for strong models and keeps the turn-start injection; `--gated` adds a deliberate Stop-hook completion gate that blocks only when five conditions hold (gated mode, an `in_progress` phase, `stop_hook_active` false, block count under the cap, ledger progressed since the last block), so an incomplete plan alone never traps a session. New append-only JSONL run ledger (`ledger-append`, `ledger-summary`, `phase-status`, sh + ps1) replaces the raw `progress.md` tail in v3 modes with a fixed-shape summary. Attestation is default-on in v3 modes and unattested plan bodies are refused at injection. Per-session nonce delimiters, SHA cache moved to `$XDG_CACHE_HOME/pwf-sha`, realpath containment in the plan-dir resolver. Hook scalars replaced by thin dispatchers (`inject-plan.sh`, `gate-stop.sh`) shipped in both `scripts/` locations. New `templates/task_plan_autonomous.md` with `DependsOn`/`Owner`/`AcceptanceCheck` fields, v2-to-v3 migration guide in `MIGRATION.md`, host capability tiers documented (hard block, follow-up inject, notify only). Suite at 178 passed plus location-parity and gate/ledger/init-mode/containment tests. |
|
||||
@@ -146,7 +149,7 @@ When your context fills up and you run `/clear`, this skill **automatically reco
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🛠️ Supported IDEs (17+ Platforms)</strong></summary>
|
||||
<summary><strong>🛠️ Supported IDEs (18+ Platforms)</strong></summary>
|
||||
|
||||
#### Enhanced Support (hooks + lifecycle automation)
|
||||
|
||||
@@ -175,6 +178,7 @@ These IDEs implement the [Agent Skills](https://agentskills.io) open specificati
|
||||
| Continue | [Continue Setup](docs/continue.md) | `.continue/skills/` + [.prompt files](https://docs.continue.dev/customize/deep-dives/prompts) |
|
||||
| Pi Agent | [Pi Agent Setup](docs/pi-agent.md) | `.pi/skills/` ([npm package](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)) |
|
||||
| OpenClaw | [OpenClaw Setup](docs/openclaw.md) | `.openclaw/skills/` ([docs](https://docs.openclaw.ai/tools/skills)) |
|
||||
| Autohand Code | [Autohand Code Setup](docs/autohand.md) | `~/.autohand/skills/` or `.autohand/skills/` |
|
||||
| Antigravity | [Antigravity Setup](docs/antigravity.md) | `.agent/skills/` ([docs](https://codelabs.developers.google.com/getting-started-with-antigravity-skills)) |
|
||||
| Kilocode | [Kilocode Setup](docs/kilocode.md) | `.kilocode/skills/` ([docs](https://kilo.ai/docs/agent-behavior/skills)) |
|
||||
| AdaL CLI (Sylph AI) | [AdaL Setup](docs/adal.md) | `.adal/skills/` ([docs](https://docs.sylph.ai/features/plugins-and-skills)) |
|
||||
@@ -248,7 +252,7 @@ npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g
|
||||
|
||||
</details>
|
||||
|
||||
Works with Claude Code, Cursor, Codex, Gemini CLI, and 40+ agents supporting the [Agent Skills](https://agentskills.io) spec.
|
||||
Works with Claude Code, Cursor, Codex, Gemini CLI, Autohand Code, and 40+ agents supporting the [Agent Skills](https://agentskills.io) spec.
|
||||
|
||||
<details>
|
||||
<summary><strong>🔧 Claude Code Plugin (Advanced Features)</strong></summary>
|
||||
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
# Security Policy
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
Report suspected vulnerabilities privately through [GitHub Private Vulnerability Reporting](https://github.com/OthmanAdi/planning-with-files/security/advisories/new) (Security tab -> Report a vulnerability). This opens a private advisory visible only to the maintainer until a fix ships.
|
||||
|
||||
Include what you'd include in a normal bug report, plus:
|
||||
|
||||
- The affected hook, script, or file (e.g. `scripts/inject-plan.sh`, a specific IDE's `hooks/stop.sh`).
|
||||
- The data flow: what untrusted input reaches what trusted context.
|
||||
- Reproduction steps.
|
||||
- Suggested mitigation, if you have one.
|
||||
|
||||
Do not open a public issue for a suspected vulnerability before it's been triaged privately.
|
||||
|
||||
## Scope
|
||||
|
||||
This repository ships markdown-based planning templates plus shell/PowerShell/Python hook scripts that several AI coding agents (Claude Code, Codex, Cursor, GitHub Copilot, and others) execute automatically during a session. Relevant security concerns include:
|
||||
|
||||
- Prompt injection via plan file content reaching model context (see the delimiter and attestation mechanisms in `scripts/inject-plan.sh` and `scripts/attest-plan.sh`).
|
||||
- Path traversal or symlink escapes in plan directory resolution (`scripts/resolve-plan-dir.sh`, `scripts/inject-plan.sh`'s containment guard).
|
||||
- Supply-chain concerns in any dependency, install script, or bin shim (this repo currently has none; flag if that changes).
|
||||
|
||||
Not in scope: vulnerabilities in the AI agents/IDEs themselves (Claude Code, Codex, etc.) — report those to their respective maintainers.
|
||||
|
||||
## Response
|
||||
|
||||
Expect an initial response within a few days. Confirmed fixes ship as a patch release with a CHANGELOG `### Security` entry; credit is given in `CONTRIBUTORS.md` unless you ask to stay anonymous.
|
||||
|
||||
## Supported Versions
|
||||
|
||||
Only the latest released version is supported. Update to the current release before reporting if you're on an older one.
|
||||
+6
-3
@@ -29,21 +29,24 @@ How to use planning-with-files with AdaL CLI (Sylph AI).
|
||||
|
||||
```bash
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
cp -r planning-with-files/.adal/skills/planning-with-files ~/.adal/skills/
|
||||
mkdir -p ~/.adal/skills
|
||||
cp -r planning-with-files/skills/planning-with-files ~/.adal/skills/
|
||||
```
|
||||
|
||||
### Option 3: Copy to project skills directory
|
||||
|
||||
```bash
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
cp -r planning-with-files/.adal/skills/planning-with-files .adal/skills/
|
||||
mkdir -p .adal/skills
|
||||
cp -r planning-with-files/skills/planning-with-files .adal/skills/
|
||||
```
|
||||
|
||||
### Option 4: Windows (PowerShell)
|
||||
|
||||
```powershell
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
Copy-Item -Recurse -Path "planning-with-files\.adal\skills\planning-with-files" -Destination "$env:USERPROFILE\.adal\skills\"
|
||||
New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.adal\skills
|
||||
Copy-Item -Recurse -Path "planning-with-files\skills\planning-with-files" -Destination "$env:USERPROFILE\.adal\skills\"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
+9
-8
@@ -16,8 +16,9 @@ Share the skill with your entire team by adding it to your repository:
|
||||
# In your project repository
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
|
||||
|
||||
# Copy the Antigravity skill to your repo
|
||||
cp -r /tmp/planning-with-files/.agent .
|
||||
# Copy the planning-with-files skill to your repo
|
||||
mkdir -p .agent/skills
|
||||
cp -r /tmp/planning-with-files/skills/planning-with-files .agent/skills/
|
||||
|
||||
# Commit to share with team
|
||||
git add .agent/
|
||||
@@ -40,7 +41,7 @@ git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-wit
|
||||
|
||||
# Copy to your personal Antigravity skills folder
|
||||
mkdir -p ~/.gemini/antigravity/skills
|
||||
cp -r /tmp/planning-with-files/.agent/skills/planning-with-files ~/.gemini/antigravity/skills/
|
||||
cp -r /tmp/planning-with-files/skills/planning-with-files ~/.gemini/antigravity/skills/
|
||||
|
||||
# Clean up
|
||||
rm -rf /tmp/planning-with-files
|
||||
@@ -97,7 +98,7 @@ Once activated, the skill creates:
|
||||
|
||||
### Templates
|
||||
|
||||
The skill includes starter templates in `.agent/skills/planning-with-files/references/`:
|
||||
The skill includes starter templates in `.agent/skills/planning-with-files/templates/`:
|
||||
- `task_plan.md` — Phase tracking template
|
||||
- `findings.md` — Research storage template
|
||||
- `progress.md` — Session logging template
|
||||
@@ -208,9 +209,9 @@ Check:
|
||||
|
||||
### Need Templates?
|
||||
|
||||
Templates are in:
|
||||
- **Workspace:** `.agent/skills/planning-with-files/references/`
|
||||
- **Personal:** `~/.gemini/antigravity/skills/planning-with-files/references/`
|
||||
Check:
|
||||
- **Workspace:** `.agent/skills/planning-with-files/templates/`
|
||||
- **Personal:** `~/.gemini/antigravity/skills/planning-with-files/templates/`
|
||||
|
||||
Copy them to your project root and customize.
|
||||
|
||||
@@ -229,7 +230,7 @@ Edit `.agent/skills/planning-with-files/SKILL.md` to customize:
|
||||
|
||||
Place custom templates in:
|
||||
```
|
||||
.agent/skills/planning-with-files/references/
|
||||
.agent/skills/planning-with-files/templates/
|
||||
```
|
||||
|
||||
Antigravity will reference them automatically.
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
# Autohand Code Setup
|
||||
|
||||
How to use planning-with-files with [Autohand Code](https://github.com/autohandai/code-cli/).
|
||||
|
||||
---
|
||||
|
||||
## What This Integration Adds
|
||||
|
||||
- Standard Agent Skill loading through Autohand Code skill discovery.
|
||||
- Full templates, scripts, and reference documentation from the canonical skill.
|
||||
- User-level or project-level installs.
|
||||
|
||||
Autohand Code discovers skills from multiple locations, including:
|
||||
|
||||
1. **User-level skills:** `~/.autohand/skills/`
|
||||
2. **Project-level skills:** `<project>/.autohand/skills/`
|
||||
3. **Shared Agent Skills:** `~/.agents/skills/`
|
||||
|
||||
---
|
||||
|
||||
## Installation (standard Agent Skills)
|
||||
|
||||
Install with the shared Agent Skills installer:
|
||||
|
||||
```bash
|
||||
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
|
||||
```
|
||||
|
||||
This installs into the shared Agent Skills convention that Autohand Code can scan.
|
||||
|
||||
---
|
||||
|
||||
## Installation (Autohand-native user scope)
|
||||
|
||||
Install just for your user account:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
|
||||
mkdir -p ~/.autohand/skills
|
||||
cp -r /tmp/planning-with-files/skills/planning-with-files ~/.autohand/skills/
|
||||
rm -rf /tmp/planning-with-files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation (Autohand-native project scope)
|
||||
|
||||
Commit the skill to a project so the whole team gets the same planning workflow:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
|
||||
mkdir -p .autohand/skills
|
||||
cp -r /tmp/planning-with-files/skills/planning-with-files .autohand/skills/
|
||||
git add .autohand/skills/planning-with-files
|
||||
git commit -m "Add planning-with-files skill for Autohand Code"
|
||||
rm -rf /tmp/planning-with-files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Autohand Catalog Skills
|
||||
|
||||
Autohand Code can browse its community catalog with:
|
||||
|
||||
```bash
|
||||
autohand --skill-install
|
||||
```
|
||||
|
||||
Project-scoped catalog installs use:
|
||||
|
||||
```bash
|
||||
autohand --skill-install <skill-name> --project
|
||||
```
|
||||
|
||||
For this repository, use `npx skills add` or the direct clone paths above unless the skill appears in the Autohand catalog.
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
Start Autohand Code in your project. For complex tasks, the skill guides the agent to create and maintain:
|
||||
|
||||
- `task_plan.md` — phases, progress, and decisions
|
||||
- `findings.md` — research and discoveries
|
||||
- `progress.md` — session log and test results
|
||||
|
||||
The planning files live in your project root, not inside the skill directory.
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- This is standard Agent Skills support. Claude Code plugin commands and Claude-specific hooks are not installed by this path.
|
||||
- The underlying planning files are tool-agnostic and work across Claude Code, Cursor, Codex, Autohand Code, and other agents.
|
||||
- If you use both shared `~/.agents/skills/` and Autohand-native directories, avoid installing duplicate copies of the same skill.
|
||||
+4
-4
@@ -97,7 +97,7 @@ Once activated, the skill creates:
|
||||
|
||||
### Templates
|
||||
|
||||
The skill includes starter templates in `.codebuddy/skills/planning-with-files/references/`:
|
||||
The skill includes starter templates in `.codebuddy/skills/planning-with-files/templates/`:
|
||||
- `task_plan.md` — Phase tracking template
|
||||
- `findings.md` — Research storage template
|
||||
- `progress.md` — Session logging template
|
||||
@@ -209,8 +209,8 @@ Check:
|
||||
### Need Templates?
|
||||
|
||||
Templates are in:
|
||||
- **Workspace:** `.codebuddy/skills/planning-with-files/references/`
|
||||
- **Personal:** `~/.codebuddy/skills/planning-with-files/references/`
|
||||
- **Workspace:** `.codebuddy/skills/planning-with-files/templates/`
|
||||
- **Personal:** `~/.codebuddy/skills/planning-with-files/templates/`
|
||||
|
||||
Copy them to your project root and customize.
|
||||
|
||||
@@ -229,7 +229,7 @@ Edit `.codebuddy/skills/planning-with-files/SKILL.md` to customize:
|
||||
|
||||
Place custom templates in:
|
||||
```
|
||||
.codebuddy/skills/planning-with-files/references/
|
||||
.codebuddy/skills/planning-with-files/templates/
|
||||
```
|
||||
|
||||
CodeBuddy will reference them automatically.
|
||||
|
||||
+50
-3
@@ -1,6 +1,6 @@
|
||||
# Benchmark Results — planning-with-files v2.22.0
|
||||
# Benchmark Results: planning-with-files
|
||||
|
||||
Formal evaluation of `planning-with-files` using Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) framework. This document records the full methodology, test cases, grading criteria, and results.
|
||||
Formal evaluation of `planning-with-files` using Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) framework, plus later functional verification of v3-specific mechanisms. This document records the full methodology, test cases, grading criteria, and results. Tests 1 through 3 were run against v2.22.0 (2026-03-06); Test 4 was run against v3.2.0 (2026-07-03).
|
||||
|
||||
---
|
||||
|
||||
@@ -136,6 +136,52 @@ Requires `ANTHROPIC_API_KEY` in the eval environment. Per the project's eval sta
|
||||
|
||||
---
|
||||
|
||||
## Test 4: v3 Long-Running Session Functional Verification (2026-07-03)
|
||||
|
||||
Tests 1 through 3 measure whether the skill enforces the 3-file planning pattern. They predate v3.0.0 (2026-06-09) and say nothing about v3's own headline feature: surviving `/clear` and context compaction across a long-running session. This section covers that mechanism specifically, added after a repository health audit found it was silently broken on Windows.
|
||||
|
||||
### Method
|
||||
|
||||
Rather than reading the code and assuming it worked, each mechanism was run directly in a scratch directory on a real Windows machine (Git Bash and PowerShell, both), with real files and real tampering, checking actual command output against expectations.
|
||||
|
||||
### Scope
|
||||
|
||||
| Mechanism | Script | What it does |
|
||||
|-----------|--------|---------------|
|
||||
| Session init | `init-session.sh` / `.ps1` | Creates `task_plan.md`, `findings.md`, `progress.md` from templates |
|
||||
| Phase status | `check-complete.sh` / `.ps1` | Counts phases, reports completion |
|
||||
| Attestation | `attest-plan.sh` / `.ps1` | SHA-256 locks plan content, detects tampering |
|
||||
| Plan injection | `inject-plan.sh` | Re-injects plan context into the model turn, enforces the attestation |
|
||||
| Parallel plans | `resolve-plan-dir.sh` / `.ps1` | Resolves the active plan directory across concurrent sessions |
|
||||
| Session recovery | `session-catchup.py` | Reconstructs unsynced context after `/clear`, the actual "long-running session" mechanism |
|
||||
|
||||
### Result: 2 of 6 mechanisms were broken on Windows, silently
|
||||
|
||||
**`session-catchup.py` did nothing on Windows.** Two independent bugs, either one alone sufficient to break it:
|
||||
|
||||
1. The path sanitizer only replaced forward slashes. A Windows path (`C:\Users\...` or Git Bash's `/c/Users/...`) never matched Claude's actual project-directory naming, so the function always returned before finding any sessions to scan.
|
||||
2. Three file reads had no explicit encoding, so any session log containing non-ASCII text raised `UnicodeDecodeError` against Windows' default `cp1252` codec, an error the surrounding `except` clauses swallowed without a trace.
|
||||
|
||||
Neither failure printed anything. A user running this on Windows would see no catchup report and have no reason to suspect the mechanism was even running, let alone why it produced nothing. `tests/test_path_fix.py` contained a working reimplementation of the correct fix but never imported or exercised the actual shipped script, so the test suite reported green the entire time.
|
||||
|
||||
**`inject-plan.sh`'s containment guard silently dropped plan injection under aliased paths.** The guard canonicalizes the project root and the candidate plan directory separately, then checks that one is a prefix of the other. On a Windows account with an 8.3 short-name `TEMP` (this test machine's own account is one such case) or a path reached through the MSYS `/tmp` mount, the two canonicalization routes land on differently-spelled versions of the same directory, the prefix check fails, and the hook exits with zero output: no plan re-injection, no tamper warning, nothing. `resolve-plan-dir.sh` does not have this bug because it builds its candidates as absolute paths from the start; that asymmetry is what pointed at the fix.
|
||||
|
||||
### What worked correctly, unmodified
|
||||
|
||||
Session init, phase-status counting, attestation lock/show/clear, tamper detection logic itself (once the injection guard reaches it), and parallel-plan directory resolution (`$PLAN_ID` env var, `.active_plan` file, newest-mtime fallback) all produced correct output in both Git Bash and PowerShell, including the v3 autonomous-mode chain (nonce-framed delimiters, unattested-plan refusal, per-tool-call injection suppression).
|
||||
|
||||
One asymmetry noted but not a bug: `init-session.ps1` has no slug mode (it always writes to the project root), only `init-session.sh` creates `.planning/<slug>/` directories. And there is no `inject-plan.ps1`; the injection and tamper-enforcement hook body is sh-only, so a pure-PowerShell host without Git Bash gets no plan injection or tamper enforcement at all.
|
||||
|
||||
### Fixed in v3.2.0
|
||||
|
||||
Both `session-catchup.py` and `inject-plan.sh` were fixed (see CHANGELOG). Re-running the same sequence after the fix confirmed session-catchup now produces a correct catchup report from real session logs, and plan injection now reaches the tamper-check branch under the same aliased-path conditions that previously went silent. The PowerShell-only injection gap and the `init-session.ps1` slug-mode asymmetry are open follow-ups, not addressed in this cycle.
|
||||
|
||||
### A caveat on what session-catchup actually does, working or not
|
||||
|
||||
Even fixed, `session-catchup.py` replays conversation transcript from the previous session; it does not parse or reconstruct the on-disk phase state directly. Its own "RECOMMENDED" output tells the agent to go read `task_plan.md`, `progress.md`, and `findings.md` itself. It is a conversation catchup that points at the files, not a plan-state reconstruction, and its usefulness is bounded by how much relevant discussion happened after the last planning-file edit.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Test | Status | Result |
|
||||
@@ -143,8 +189,9 @@ Requires `ANTHROPIC_API_KEY` in the eval environment. Per the project's eval sta
|
||||
| Evals + Benchmark | ✅ Complete | 96.7% (with_skill) vs 6.7% (without_skill) |
|
||||
| A/B Blind Comparison | ✅ Complete | 3/3 wins (100%) for with_skill |
|
||||
| Description Optimizer | Pending | Scheduled for next eval cycle |
|
||||
| v3 Long-Running Session Functional Verification | ✅ Complete (2026-07-03) | 2 of 6 mechanisms found broken on Windows and fixed in v3.2.0; see Test 4 |
|
||||
|
||||
The skill demonstrably enforces the 3-file planning pattern across diverse task types. Without the skill, agents default to ad-hoc file naming and skip the structured planning workflow entirely.
|
||||
The skill demonstrably enforces the 3-file planning pattern across diverse task types. Without the skill, agents default to ad-hoc file naming and skip the structured planning workflow entirely. Separately, v3's session-recovery mechanism is now verified functional on Windows as of v3.2.0; it was not before, and nothing in the test suite would have caught that on its own.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+6
-6
@@ -21,7 +21,7 @@ git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
|
||||
# Copy the skill to Kilo Code's skills directory
|
||||
mkdir -p .kilocode/skills
|
||||
cp -r planning-with-files/.kilocode/skills/planning-with-files .kilocode/skills/planning-with-files
|
||||
cp -r planning-with-files/skills/planning-with-files .kilocode/skills/
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
@@ -31,7 +31,7 @@ git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
|
||||
# Copy the skill to Kilo Code's skills directory
|
||||
New-Item -ItemType Directory -Force -Path .kilocode\skills
|
||||
Copy-Item -Recurse -Force planning-with-files\.kilocode\skills\planning-with-files .kilocode\skills\planning-with-files
|
||||
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\
|
||||
```
|
||||
|
||||
### Manual Installation (Project-Level)
|
||||
@@ -42,14 +42,14 @@ Copy the skill directory to your project:
|
||||
```bash
|
||||
# From the cloned repository
|
||||
mkdir -p .kilocode/skills
|
||||
cp -r planning-with-files/.kilocode/skills/planning-with-files .kilocode/skills/planning-with-files
|
||||
cp -r planning-with-files/skills/planning-with-files .kilocode/skills/
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
# From the cloned repository
|
||||
New-Item -ItemType Directory -Force -Path .kilocode\skills
|
||||
Copy-Item -Recurse -Force planning-with-files\.kilocode\skills\planning-with-files .kilocode\skills\planning-with-files
|
||||
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files .kilocode\skills\
|
||||
```
|
||||
|
||||
### Global Installation (User-Level)
|
||||
@@ -60,14 +60,14 @@ To make the skill available across all projects:
|
||||
```bash
|
||||
# Copy to global skills directory
|
||||
mkdir -p ~/.kilocode/skills
|
||||
cp -r planning-with-files/.kilocode/skills/planning-with-files ~/.kilocode/skills/planning-with-files
|
||||
cp -r planning-with-files/skills/planning-with-files ~/.kilocode/skills/
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
# Copy to global skills directory (replace YourUsername with your actual username)
|
||||
New-Item -ItemType Directory -Force -Path C:\Users\YourUsername\.kilocode\skills
|
||||
Copy-Item -Recurse -Force planning-with-files\.kilocode\skills\planning-with-files C:\Users\YourUsername\.kilocode\skills\planning-with-files
|
||||
Copy-Item -Recurse -Force planning-with-files\skills\planning-with-files C:\Users\YourUsername\.kilocode\skills\
|
||||
```
|
||||
|
||||
### Verifying Installation
|
||||
|
||||
+2
-2
@@ -39,7 +39,7 @@ git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
|
||||
# Copy the skill files to your workspace
|
||||
mkdir -p skills/planning-with-files
|
||||
cp -r planning-with-files/clawhub-upload/* skills/planning-with-files/
|
||||
cp -r planning-with-files/skills/planning-with-files/* skills/planning-with-files/
|
||||
|
||||
# Clean up
|
||||
rm -rf planning-with-files
|
||||
@@ -57,7 +57,7 @@ git clone https://github.com/OthmanAdi/planning-with-files.git
|
||||
|
||||
# Copy to global OpenClaw skills
|
||||
mkdir -p ~/.openclaw/skills/planning-with-files
|
||||
cp -r planning-with-files/clawhub-upload/* ~/.openclaw/skills/planning-with-files/
|
||||
cp -r planning-with-files/skills/planning-with-files/* ~/.openclaw/skills/planning-with-files/
|
||||
|
||||
# Clean up
|
||||
rm -rf planning-with-files
|
||||
|
||||
@@ -73,6 +73,13 @@ $COMPLETE = [Math]::Max($completePrimary, $completeInline)
|
||||
$IN_PROGRESS = [Math]::Max($inProgressPrimary, $inProgressInline)
|
||||
$PENDING = [Math]::Max($pendingPrimary, $pendingInline)
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if ($TOTAL -eq 0) {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# advisory_report: the v2.43 status echo.
|
||||
function Write-AdvisoryReport {
|
||||
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
|
||||
|
||||
@@ -97,6 +97,13 @@ if [ "$PENDING_INLINE" -gt "$PENDING_PRIMARY" ]; then PENDING="$PENDING_INLINE";
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
|
||||
advisory_report() {
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
|
||||
@@ -69,7 +69,13 @@ canonicalize() {
|
||||
# and python; the SLUG_RE check already blocks traversal in the slug name.
|
||||
is_within_root() {
|
||||
candidate="$1"
|
||||
root_real="$(canonicalize "${PWD}")" || root_real=""
|
||||
# Canonicalize the root via the relative token "." rather than the $PWD
|
||||
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount
|
||||
# alias) realpath("$PWD") and realpath(relative-candidate) resolve through
|
||||
# different code paths and land on differently-spelled-but-equal targets,
|
||||
# so the prefix match below fails and injection silently goes dark. "."
|
||||
# resolves through the same physical-cwd path candidates already use.
|
||||
root_real="$(canonicalize ".")" || root_real=""
|
||||
cand_real="$(canonicalize "${candidate}")" || cand_real=""
|
||||
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
|
||||
return 0
|
||||
|
||||
@@ -45,10 +45,29 @@ def detect_ide() -> str:
|
||||
|
||||
|
||||
def get_project_dir_claude(project_path: str) -> Path:
|
||||
"""Convert project path to Claude's storage path format."""
|
||||
sanitized = project_path.replace('/', '-')
|
||||
if not sanitized.startswith('-'):
|
||||
sanitized = '-' + sanitized
|
||||
"""Convert project path to Claude's storage path format.
|
||||
|
||||
Windows paths (C:\\Users\\... or Git Bash /c/Users/...) need the drive
|
||||
colon and backslashes sanitized too, not just forward slashes, and
|
||||
Claude's actual sanitized form has no leading dash for those (the drive
|
||||
letter isn't a separator). Real Unix absolute paths keep their existing
|
||||
leading-dash behavior unchanged (path is used as-is, matching Claude's
|
||||
convention there).
|
||||
"""
|
||||
p = project_path
|
||||
if len(p) >= 3 and p[0] == '/' and p[2] == '/' and p[1].isalpha():
|
||||
# Git Bash / MSYS2: /c/Users/... -> C:/Users/...
|
||||
p = p[1].upper() + ':' + p[2:]
|
||||
if ':' in p or '\\' in p:
|
||||
try:
|
||||
p = str(Path(p).resolve())
|
||||
except (OSError, ValueError):
|
||||
pass
|
||||
sanitized = p.replace('\\', '-').replace('/', '-').replace(':', '-')
|
||||
else:
|
||||
sanitized = p.replace('/', '-')
|
||||
if not sanitized.startswith('-'):
|
||||
sanitized = '-' + sanitized
|
||||
sanitized = sanitized.replace('_', '-')
|
||||
return Path.home() / '.claude' / 'projects' / sanitized
|
||||
|
||||
@@ -99,7 +118,7 @@ def get_sessions_sorted_opencode(storage_dir: Path) -> List[Path]:
|
||||
def get_session_first_timestamp(session_file: Path) -> Optional[str]:
|
||||
"""Get the timestamp of the first message in a session."""
|
||||
try:
|
||||
with open(session_file, 'r') as f:
|
||||
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
|
||||
for line in f:
|
||||
try:
|
||||
data = json.loads(line)
|
||||
@@ -122,7 +141,7 @@ def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
|
||||
last_update_file = None
|
||||
|
||||
try:
|
||||
with open(session_file, 'r') as f:
|
||||
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
|
||||
for line_num, line in enumerate(f):
|
||||
if '"Write"' not in line and '"Edit"' not in line:
|
||||
continue
|
||||
@@ -166,7 +185,7 @@ def extract_messages_from_session(session_file: Path, after_line: int = -1) -> L
|
||||
result = []
|
||||
|
||||
try:
|
||||
with open(session_file, 'r') as f:
|
||||
with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
|
||||
for line_num, line in enumerate(f):
|
||||
if after_line >= 0 and line_num <= after_line:
|
||||
continue
|
||||
|
||||
@@ -33,6 +33,8 @@ TEMPLATES = [
|
||||
"templates/findings.md",
|
||||
"templates/progress.md",
|
||||
"templates/task_plan.md",
|
||||
"templates/analytics_task_plan.md",
|
||||
"templates/analytics_findings.md",
|
||||
]
|
||||
|
||||
REFERENCES = [
|
||||
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
---
|
||||
|
||||
# نظام تخطيط الملفات
|
||||
@@ -44,7 +44,8 @@ metadata:
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
||||
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files-ar}"
|
||||
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
|
||||
@@ -32,6 +32,11 @@ fi
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# الإبلاغ عن الحالة (ينهي دائمًا برمز خروج 0 — المهام غير المكتملة حالة طبيعية)
|
||||
# issue #191: TOTAL=0 -> not phase-structured, stay silent
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
echo "[planning-with-files-ar] اكتملت جميع المراحل ($COMPLETE/$TOTAL). إذا كان لدى المستخدم عمل إضافي، أضف مراحل في task_plan.md قبل البدء."
|
||||
else
|
||||
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
---
|
||||
|
||||
# Dateiplanungssystem
|
||||
@@ -44,7 +44,8 @@ Arbeite wie Manus: Verwende persistente Markdown-Dateien als deinen „Festplatt
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
||||
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files-de}"
|
||||
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
|
||||
@@ -32,6 +32,11 @@ fi
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# Status melden (immer mit Exit-Code 0 beenden — unvollständige Aufgaben sind normaler Zustand)
|
||||
# issue #191: TOTAL=0 -> not phase-structured, stay silent
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
echo "[planning-with-files-de] Alle Phasen abgeschlossen ($COMPLETE/$TOTAL). Wenn der Benutzer zusätzliche Arbeit hat, neue Phasen in task_plan.md hinzufügen, bevor du beginnst."
|
||||
else
|
||||
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
---
|
||||
|
||||
# Sistema de Planificación con Archivos
|
||||
@@ -44,7 +44,8 @@ Trabaja como Manus: usa archivos Markdown persistentes como tu «memoria de trab
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
||||
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files-es}"
|
||||
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
|
||||
@@ -32,6 +32,11 @@ fi
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# Informar estado (siempre salir con código 0 — tareas incompletas son estado normal)
|
||||
# issue #191: TOTAL=0 -> not phase-structured, stay silent
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
echo "[planning-with-files-es] Todas las fases completadas ($COMPLETE/$TOTAL). Si el usuario tiene trabajo adicional, añadir fases en task_plan.md antes de comenzar."
|
||||
else
|
||||
|
||||
@@ -29,7 +29,7 @@ hooks:
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
|
||||
---
|
||||
|
||||
@@ -46,7 +46,8 @@ metadata:
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
||||
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files-zh}"
|
||||
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
|
||||
@@ -32,6 +32,11 @@ fi
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# 报告状态（始终以退出码 0 结束 — 未完成的任务是正常状态）
|
||||
# issue #191: TOTAL=0 -> not phase-structured, stay silent
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
echo "[planning-with-files] 所有阶段已完成（$COMPLETE/$TOTAL）。如果用户有额外工作，请在开始前于 task_plan.md 中新增阶段。"
|
||||
else
|
||||
|
||||
@@ -29,7 +29,7 @@ hooks:
|
||||
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
|
||||
metadata:
|
||||
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
|
||||
---
|
||||
|
||||
@@ -46,7 +46,8 @@ metadata:
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
||||
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files-zht}"
|
||||
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
|
||||
@@ -32,6 +32,11 @@ fi
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# 回報狀態（始終以退出碼 0 結束 — 未完成的任務是正常狀態）
|
||||
# issue #191: TOTAL=0 -> not phase-structured, stay silent
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
echo "[planning-with-files] 所有階段已完成（$COMPLETE/$TOTAL）。如果使用者有額外工作，請在開始前於 task_plan.md 中新增階段。"
|
||||
else
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: planning-with-files
|
||||
description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
|
||||
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear."
|
||||
user-invocable: true
|
||||
allowed-tools: "Read Write Edit Bash Glob Grep"
|
||||
hooks:
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.1.1"
|
||||
version: "3.2.0"
|
||||
---
|
||||
|
||||
# Planning with Files
|
||||
@@ -43,8 +43,9 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
|
||||
2. Then check for unsynced context from a previous session:
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
||||
# Linux/macOS — auto-detects skill directory (plugin env or default install path)
|
||||
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"
|
||||
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"
|
||||
```
|
||||
|
||||
```powershell
|
||||
|
||||
@@ -73,6 +73,13 @@ $COMPLETE = [Math]::Max($completePrimary, $completeInline)
|
||||
$IN_PROGRESS = [Math]::Max($inProgressPrimary, $inProgressInline)
|
||||
$PENDING = [Math]::Max($pendingPrimary, $pendingInline)
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if ($TOTAL -eq 0) {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# advisory_report: the v2.43 status echo.
|
||||
function Write-AdvisoryReport {
|
||||
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
|
||||
|
||||
@@ -97,6 +97,13 @@ if [ "$PENDING_INLINE" -gt "$PENDING_PRIMARY" ]; then PENDING="$PENDING_INLINE";
|
||||
: "${IN_PROGRESS:=0}"
|
||||
: "${PENDING:=0}"
|
||||
|
||||
# issue #191: no "### Phase" headings -> not a phase-structured plan. Report
|
||||
# nothing rather than a false "0/0 phases complete" status. With TOTAL=0 the
|
||||
# gate can never legitimately block (IN_PROGRESS is also 0), so exit is safe.
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
|
||||
advisory_report() {
|
||||
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
|
||||
|
||||
@@ -69,7 +69,13 @@ canonicalize() {
|
||||
# and python; the SLUG_RE check already blocks traversal in the slug name.
|
||||
is_within_root() {
|
||||
candidate="$1"
|
||||
root_real="$(canonicalize "${PWD}")" || root_real=""
|
||||
# Canonicalize the root via the relative token "." rather than the $PWD
|
||||
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount
|
||||
# alias) realpath("$PWD") and realpath(relative-candidate) resolve through
|
||||
# different code paths and land on differently-spelled-but-equal targets,
|
||||
# so the prefix match below fails and injection silently goes dark. "."
|
||||
# resolves through the same physical-cwd path candidates already use.
|
||||
root_real="$(canonicalize ".")" || root_real=""
|
||||
cand_real="$(canonicalize "${candidate}")" || cand_real=""
|
||||
if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
|
||||
return 0
|
||||
|
||||
@@ -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
|
||||
@@ -81,6 +81,7 @@ class CanonicalScriptSyncTests(unittest.TestCase):
|
||||
[sys.executable, str(REPO_ROOT / "scripts" / "sync-ide-folders.py"), "--verify"],
|
||||
cwd=str(REPO_ROOT),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
|
||||
@@ -70,6 +70,7 @@ class CheckCompleteResolverTests(unittest.TestCase):
|
||||
cmd,
|
||||
cwd=str(cwd),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
|
||||
@@ -20,6 +20,7 @@ class CodexHooksTests(unittest.TestCase):
|
||||
[sys.executable, str(HOOKS_DIR / script_name)],
|
||||
input=json.dumps(payload),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
cwd=str(cwd),
|
||||
check=False,
|
||||
@@ -29,6 +30,7 @@ class CodexHooksTests(unittest.TestCase):
|
||||
return subprocess.run(
|
||||
["sh", str(HOOKS_DIR / script_name)],
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
cwd=str(cwd),
|
||||
env=env,
|
||||
|
||||
@@ -34,6 +34,7 @@ class CodexSessionIsolationTests(unittest.TestCase):
|
||||
[sys.executable, str(HOOKS_DIR / script_name)],
|
||||
input=json.dumps(payload),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
cwd=str(cwd),
|
||||
check=False,
|
||||
@@ -65,6 +66,7 @@ class CodexSessionIsolationTests(unittest.TestCase):
|
||||
["sh", str(HOOKS_DIR / "user-prompt-submit.sh")],
|
||||
cwd=str(root),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env={**os.environ, "PWF_SESSION_ID": "sess-A"},
|
||||
check=False,
|
||||
@@ -86,6 +88,7 @@ class CodexSessionIsolationTests(unittest.TestCase):
|
||||
["sh", str(HOOKS_DIR / "user-prompt-submit.sh")],
|
||||
cwd=str(root),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
@@ -102,6 +105,7 @@ class CodexSessionIsolationTests(unittest.TestCase):
|
||||
["sh", str(HOOKS_DIR / "user-prompt-submit.sh")],
|
||||
cwd=str(root),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
@@ -146,11 +150,11 @@ class CodexSessionIsolationTests(unittest.TestCase):
|
||||
env_b = {**os.environ, "PWF_SESSION_ID": "sess-B"}
|
||||
ra = subprocess.run(
|
||||
["sh", str(HOOKS_DIR / "user-prompt-submit.sh")],
|
||||
cwd=str(root), text=True, capture_output=True, env=env_a, check=False,
|
||||
cwd=str(root), text=True, encoding="utf-8", capture_output=True, env=env_a, check=False,
|
||||
)
|
||||
rb = subprocess.run(
|
||||
["sh", str(HOOKS_DIR / "user-prompt-submit.sh")],
|
||||
cwd=str(root), text=True, capture_output=True, env=env_b, check=False,
|
||||
cwd=str(root), text=True, encoding="utf-8", capture_output=True, env=env_b, check=False,
|
||||
)
|
||||
self.assertIn("ACTIVE PLAN", ra.stdout)
|
||||
self.assertNotIn("ACTIVE PLAN", rb.stdout)
|
||||
|
||||
@@ -75,6 +75,7 @@ class ContainmentTests(unittest.TestCase):
|
||||
["sh", str(RESOLVE_SH)],
|
||||
cwd=str(cwd),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
|
||||
@@ -90,6 +90,7 @@ class GateDecisionTableTests(unittest.TestCase):
|
||||
["sh", *args],
|
||||
cwd=str(self.tmp),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
input=json.dumps({"stop_hook_active": stop_hook_active}),
|
||||
env=env,
|
||||
|
||||
@@ -391,7 +391,11 @@ class HermesAdapterTests(unittest.TestCase):
|
||||
result = json.loads(installed_tools.planning_with_files_check_complete(cwd=str(project_dir)))
|
||||
self.assertTrue(result["ok"])
|
||||
self.assertTrue(result["complete"])
|
||||
self.assertEqual(str(skill_copy), result["skill_root"])
|
||||
# resolve_skill_dir() canonicalizes via Path.resolve(), which on Windows
|
||||
# normalizes 8.3 short-name aliases (e.g. OASRVA~1 -> oasrvadmin). Compare
|
||||
# against the same canonical form so the assertion holds regardless of
|
||||
# whether TEMP happens to be short-name-aliased on the host account.
|
||||
self.assertEqual(str(skill_copy.resolve()), result["skill_root"])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -129,6 +129,7 @@ class DispatcherScalarShapeTests(unittest.TestCase):
|
||||
["sh", str(script)],
|
||||
cwd=tmp,
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
@@ -167,6 +168,7 @@ class InjectPlanBehaviorTests(unittest.TestCase):
|
||||
["sh", str(INJECT_PLAN), f"--context={context}"],
|
||||
cwd=str(self.tmp),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=self.env,
|
||||
check=False,
|
||||
@@ -362,6 +364,7 @@ class ModeTokenParseTests(unittest.TestCase):
|
||||
["sh", str(INJECT_PLAN), f"--context={context}"],
|
||||
cwd=str(self.tmp),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=self.env,
|
||||
check=False,
|
||||
@@ -426,6 +429,7 @@ class V3AttestationRefusalTests(unittest.TestCase):
|
||||
["sh", str(INJECT_PLAN), f"--context={context}"],
|
||||
cwd=str(self.tmp),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=self.env,
|
||||
check=False,
|
||||
@@ -483,6 +487,7 @@ class ScriptAbsentWithPlanPresentTests(unittest.TestCase):
|
||||
["sh", str(script)],
|
||||
cwd=tmp,
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
|
||||
@@ -27,6 +27,7 @@ def run_hook(script: str, cwd: Path, env_extra: dict | None = None) -> subproces
|
||||
["sh", str(HOOKS_DIR / script)],
|
||||
cwd=str(cwd),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
|
||||
@@ -35,6 +35,7 @@ class InitModesTestBase(unittest.TestCase):
|
||||
["sh", str(INIT_SH), *args],
|
||||
cwd=str(cwd),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
|
||||
@@ -27,6 +27,7 @@ class InitSessionSlugTests(unittest.TestCase):
|
||||
["sh", str(INIT_SH), *args],
|
||||
cwd=str(cwd),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
|
||||
@@ -59,6 +59,7 @@ class LedgerTestBase(unittest.TestCase):
|
||||
["sh", str(LEDGER_APPEND), *args],
|
||||
cwd=str(self.tmp),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=self.env,
|
||||
check=False,
|
||||
@@ -69,6 +70,7 @@ class LedgerTestBase(unittest.TestCase):
|
||||
["sh", str(LEDGER_SUMMARY)],
|
||||
cwd=str(self.tmp),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=self.env,
|
||||
check=False,
|
||||
@@ -79,6 +81,7 @@ class LedgerTestBase(unittest.TestCase):
|
||||
["sh", str(PHASE_STATUS), *args],
|
||||
cwd=str(self.tmp),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=self.env,
|
||||
check=False,
|
||||
|
||||
+40
-50
@@ -1,59 +1,49 @@
|
||||
"""Test the path sanitization fix for session-catchup.py"""
|
||||
"""Test the path sanitization in scripts/session-catchup.py.
|
||||
|
||||
Loads the real module via importlib (the filename has a hyphen, so it can't
|
||||
be `import`-ed normally) and exercises its actual get_project_dir_claude,
|
||||
instead of reimplementing the logic here. An earlier version of this file
|
||||
reimplemented a fixed sanitizer for testing "to avoid import issues" — that
|
||||
reimplementation was correct, but it meant the suite stayed green while the
|
||||
shipped session-catchup.py (which it never touched) was still broken on
|
||||
Windows. See CHANGELOG for the fix this guards.
|
||||
"""
|
||||
import importlib.util
|
||||
import os
|
||||
import sys
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'skills', 'planning-with-files', 'scripts'))
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
MODULE_PATH = REPO_ROOT / "scripts" / "session-catchup.py"
|
||||
|
||||
# Re-implement the fix here for testing (avoids import issues)
|
||||
def normalize_path(project_path):
|
||||
p = project_path
|
||||
# Git Bash / MSYS2: /c/Users/... -> C:/Users/...
|
||||
if len(p) >= 3 and p[0] == '/' and p[2] == '/':
|
||||
p = p[1].upper() + ':' + p[2:]
|
||||
try:
|
||||
resolved = str(Path(p).resolve())
|
||||
if os.name == 'nt' or os.sep == '\\':
|
||||
p = resolved
|
||||
except (OSError, ValueError):
|
||||
pass
|
||||
return p
|
||||
spec = importlib.util.spec_from_file_location("session_catchup", MODULE_PATH)
|
||||
assert spec is not None and spec.loader is not None
|
||||
session_catchup = importlib.util.module_from_spec(spec)
|
||||
sys.modules["session_catchup"] = session_catchup
|
||||
spec.loader.exec_module(session_catchup)
|
||||
|
||||
|
||||
def sanitize(project_path):
|
||||
normalized = normalize_path(project_path)
|
||||
sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
|
||||
sanitized = sanitized.replace('_', '-')
|
||||
if sanitized.startswith('-'):
|
||||
sanitized = sanitized[1:]
|
||||
return sanitized
|
||||
class SessionCatchupPathSanitizeTests(unittest.TestCase):
|
||||
def _sanitized_name(self, project_path: str) -> str:
|
||||
project_dir = session_catchup.get_project_dir_claude(project_path)
|
||||
return project_dir.name
|
||||
|
||||
def test_windows_native_path(self) -> None:
|
||||
result = self._sanitized_name("C:/Users/oasrvadmin/Documents/planning-with-files-repo")
|
||||
self.assertEqual(result, "C--Users-oasrvadmin-Documents-planning-with-files-repo")
|
||||
|
||||
def test_git_bash_path(self) -> None:
|
||||
result = self._sanitized_name("/c/Users/oasrvadmin/Documents/planning-with-files-repo")
|
||||
self.assertEqual(result, "C--Users-oasrvadmin-Documents-planning-with-files-repo")
|
||||
|
||||
@unittest.skipIf(os.name == "nt", "exercises the real-Unix-path branch, not meaningful on Windows")
|
||||
def test_unix_absolute_path_unchanged(self) -> None:
|
||||
# Real Unix paths never contain ':' or '\\', so this must take the
|
||||
# legacy branch untouched by the Windows fix (regression guard).
|
||||
result = self._sanitized_name("/home/user/project")
|
||||
self.assertEqual(result, "-home-user-project")
|
||||
|
||||
|
||||
expected = "C--Users-oasrvadmin-Documents-planning-with-files-repo"
|
||||
|
||||
tests = {
|
||||
"Git Bash": "/c/Users/oasrvadmin/Documents/planning-with-files-repo",
|
||||
"Forward slash": "C:/Users/oasrvadmin/Documents/planning-with-files-repo",
|
||||
}
|
||||
|
||||
all_pass = True
|
||||
for label, path in tests.items():
|
||||
result = sanitize(path)
|
||||
claude_dir = Path.home() / '.claude' / 'projects' / result
|
||||
match = result == expected
|
||||
exists = claude_dir.exists()
|
||||
print(f"[{label}]")
|
||||
print(f" Input: {path}")
|
||||
print(f" Result: {result}")
|
||||
print(f" Expected: {expected}")
|
||||
print(f" Match: {match}")
|
||||
print(f" Dir exists: {exists}")
|
||||
print()
|
||||
if not match:
|
||||
all_pass = False
|
||||
|
||||
if all_pass:
|
||||
print("ALL TESTS PASSED")
|
||||
else:
|
||||
print("SOME TESTS FAILED")
|
||||
sys.exit(1)
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
@@ -54,6 +54,7 @@ class PlanAttestationTests(unittest.TestCase):
|
||||
["sh", str(self.scripts_dir / "attest-plan.sh"), *args],
|
||||
cwd=str(self.tmp),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
|
||||
@@ -94,6 +94,7 @@ class PreCompactDispatcherSilentTests(unittest.TestCase):
|
||||
["sh", str(script)],
|
||||
cwd=tmp,
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
@@ -124,6 +125,7 @@ class PreCompactBehaviorTests(unittest.TestCase):
|
||||
["sh", str(INJECT_PLAN), "--context=precompact"],
|
||||
cwd=str(self.tmp),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=self.env,
|
||||
check=False,
|
||||
|
||||
@@ -31,6 +31,7 @@ class ResolvePlanDirTests(unittest.TestCase):
|
||||
["sh", str(RESOLVE_SH)],
|
||||
cwd=str(cwd),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
env=env,
|
||||
check=False,
|
||||
|
||||
@@ -21,6 +21,7 @@ def run_set_active(cwd: Path, *args: str) -> subprocess.CompletedProcess[str]:
|
||||
["sh", str(SET_ACTIVE_SH), *args],
|
||||
cwd=str(cwd),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
@@ -90,6 +91,7 @@ class SetActivePlanTests(unittest.TestCase):
|
||||
["sh", str(resolve_sh)],
|
||||
cwd=str(root),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
@@ -100,6 +102,7 @@ class SetActivePlanTests(unittest.TestCase):
|
||||
["sh", str(resolve_sh)],
|
||||
cwd=str(root),
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
"""Guard: every SKILL.md frontmatter must be valid, loadable YAML.
|
||||
|
||||
Regression test for the v3.1.2 -> v3.1.3 break: an unquoted description that
|
||||
contained ': ' (colon followed by space) turned the frontmatter into an invalid
|
||||
YAML mapping ("mapping values are not allowed here"), which breaks skill loading
|
||||
and the model-triggering description field. The version-parity check is a regex
|
||||
and did not catch it, so this validates the frontmatter as actual YAML.
|
||||
|
||||
clawhub-upload/SKILL.md is gitignored and may be absent on a fresh clone; glob
|
||||
simply does not find it then, which is fine.
|
||||
"""
|
||||
import glob
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
def _skill_md_files():
|
||||
out = []
|
||||
for p in glob.glob(str(REPO_ROOT / "**" / "SKILL.md"), recursive=True):
|
||||
parts = Path(p).parts
|
||||
if ".git" in parts or "node_modules" in parts:
|
||||
continue
|
||||
out.append(Path(p))
|
||||
return out
|
||||
|
||||
|
||||
def _frontmatter(text):
|
||||
if not text.startswith("---"):
|
||||
return None
|
||||
segments = text.split("---", 2)
|
||||
if len(segments) < 3:
|
||||
return None
|
||||
return segments[1]
|
||||
|
||||
|
||||
def _description_line(frontmatter):
|
||||
for line in frontmatter.splitlines():
|
||||
if line.startswith("description:"):
|
||||
return line
|
||||
return None
|
||||
|
||||
|
||||
class SkillFrontmatterTests(unittest.TestCase):
|
||||
def test_files_found(self):
|
||||
self.assertTrue(_skill_md_files(), "no SKILL.md files discovered")
|
||||
|
||||
def test_every_skill_has_frontmatter_and_description(self):
|
||||
for f in _skill_md_files():
|
||||
fm = _frontmatter(f.read_text(encoding="utf-8"))
|
||||
self.assertIsNotNone(fm, f"{f} has no '---' frontmatter block")
|
||||
self.assertIsNotNone(
|
||||
_description_line(fm), f"{f} frontmatter has no description:"
|
||||
)
|
||||
|
||||
def test_unquoted_description_has_no_colon_space(self):
|
||||
# Dependency-free guard for the exact v3.1.2 break.
|
||||
for f in _skill_md_files():
|
||||
fm = _frontmatter(f.read_text(encoding="utf-8"))
|
||||
if fm is None:
|
||||
continue
|
||||
line = _description_line(fm)
|
||||
if line is None:
|
||||
continue
|
||||
value = line[len("description:"):].strip()
|
||||
if value[:1] in ('"', "'"):
|
||||
continue # quoted scalars may safely contain colons
|
||||
self.assertNotIn(
|
||||
": ",
|
||||
value,
|
||||
f"{f}: unquoted description contains ': ', which YAML parses as a "
|
||||
f"mapping and breaks frontmatter loading. Quote the value.",
|
||||
)
|
||||
|
||||
def test_frontmatter_parses_as_yaml(self):
|
||||
try:
|
||||
import yaml
|
||||
except ImportError:
|
||||
self.skipTest("PyYAML not installed")
|
||||
for f in _skill_md_files():
|
||||
fm = _frontmatter(f.read_text(encoding="utf-8"))
|
||||
if fm is None:
|
||||
continue
|
||||
try:
|
||||
data = yaml.safe_load(fm)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
self.fail(f"{f}: frontmatter is not valid YAML: {exc}")
|
||||
self.assertIsInstance(data, dict, f"{f}: frontmatter is not a mapping")
|
||||
self.assertIsInstance(
|
||||
data.get("description"),
|
||||
str,
|
||||
f"{f}: description missing or not a string after YAML parse",
|
||||
)
|
||||
self.assertTrue(
|
||||
data["description"].strip(), f"{f}: description is empty"
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user