OthmanAdi/planning-with-files / skills/planning-with-files
planning-with-files
VerifiedPersistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.
scripts/ledger-append.sh
View on GitHub#!/bin/sh
# planning-with-files: append one structured entry to the run-ledger (v3).
#
# The run-ledger is the machine layer of progress tracking: an append-only
# JSON-lines file per agent under the active plan dir. Workers append here;
# the orchestrator owns progress.md and task_plan.md. See architecture C3.
#
# Plan-dir resolution (via resolve-plan-dir.sh):
# 1. $PLAN_ID env var -> ./.planning/$PLAN_ID/
# 2. ./.planning/.active_plan
# 3. Newest ./.planning/<dir>/ by mtime
# 4. Legacy: project root (ledger lands beside ./task_plan.md)
#
# Usage:
# sh scripts/ledger-append.sh <event> <summary> [options]
#
# Arguments:
# <event> one of: progress phase_complete error gate_block attest note
# <summary> free text, truncated to 200 chars, kept valid UTF-8,
# newlines stripped
#
# Options:
# --agent NAME ledger owner (default "main"); sanitized to [A-Za-z0-9_-]
# --phase N phase number/name this entry concerns (default "")
# --files f1,f2 comma-separated file list recorded as a JSON array
#
# Writes ONE JSON line to <plan-dir>/ledger-<agent>.jsonl:
# {"tick":N,"ts":"ISO8601Z","agent":"...","phase":"...",
# "event":"...","summary":"...","files":["..."]}
#
# tick = 1 + max tick across ALL ledger-*.jsonl in the plan dir, so concurrent
# agents share a monotonic counter and the stall detector (gate C2) sees one
# ordered stream.
set -u
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
RESOLVER="${SCRIPT_DIR}/resolve-plan-dir.sh"
VALID_EVENTS="progress phase_complete error gate_block attest note"
usage() {
printf "Usage: %s <event> <summary> [--agent NAME] [--phase N] [--files f1,f2]\n" "$0" >&2
printf " event one of: %s\n" "${VALID_EVENTS}" >&2
}
resolve_plan_dir() {
plan_dir=""
if [ -f "${RESOLVER}" ]; then
plan_dir="$(sh "${RESOLVER}" 2>/dev/null)"
fi
if [ -n "${plan_dir}" ] && [ -d "${plan_dir}" ]; then
printf "%s\n" "${plan_dir}"
return 0
fi
# Explicit selectors are bindings, not hints (issue #237). This script
# WRITES ledger rows into the plan dir it picks, so a legacy cwd fallback
# after a rejected selector files another plan's run history.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
return 1
fi
# Legacy single-file mode: ledger lives beside ./task_plan.md at root.
printf "%s\n" "."
return 0
}
# Sanitize agent name to [A-Za-z0-9_-]; empty result falls back to "main".
sanitize_agent() {
raw="$1"
clean="$(printf '%s' "${raw}" | tr -cd 'A-Za-z0-9_-')"
if [ -z "${clean}" ]; then
clean="main"
fi
printf '%s' "${clean}"
}
# Escape a string for embedding inside a JSON string literal: backslash, double
# quote, and every bare control character JSON forbids. The single tr range
# 0x01-0x1F maps newline, CR, tab, vertical-tab (0x0B), form-feed (0x0C) and the
# rest of 0x01-0x08/0x0E-0x1F to spaces in one pass, matching the PS1
# ConvertTo-JsonString behavior so JSONL stays cross-platform parseable.
json_escape() {
printf '%s' "$1" \
| sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' \
| tr '\001-\037' ' '
}
# Emit $1 with any trailing incomplete UTF-8 sequence removed. GNU cut -c
# counts BYTES, so the 200 truncation below can clip a multibyte character and
# leave a tail that strict UTF-8 readers reject, poisoning the whole JSONL
# line. Preferred path: iconv -c drops every malformed byte (glibc, BSD/macOS,
# Git for Windows all ship it); its output is used whenever non-empty because
# GNU libiconv exits nonzero even after -c repaired the tail. Fallback: read
# the last <=4 bytes with od, count trailing continuation bytes (128-191),
# compare against the lead byte's declared length, drop the trailing character
# only when it is incomplete. A complete multibyte character at the boundary
# survives both paths. The fallback repairs truncation damage only; input that
# was invalid UTF-8 before truncation passes through unchanged.
utf8_trim_incomplete() {
str="$1"
if [ -z "${str}" ]; then
return 0
fi
if command -v iconv >/dev/null 2>&1; then
cleaned="$(printf '%s' "${str}" | iconv -f UTF-8 -t UTF-8 -c 2>/dev/null || true)"
if [ -n "${cleaned}" ]; then
printf '%s' "${cleaned}"
return 0
fi
# Empty output for non-empty input: iconv missing the -c flag
# (busybox) or a hard failure. Fall through to the byte-level trim.
fi
# The byte-level trim needs od, dd, and wc. On a PATH without them the
# string passes through unchanged, the pre-repair behavior: an append
# must never fail or lose the whole summary because a repair tool is
# missing.
if ! command -v od >/dev/null 2>&1 || ! command -v dd >/dev/null 2>&1; then
printf '%s' "${str}"
return 0
fi
# tr -cd normalizes BSD wc padding and yields empty when wc is absent.
nbytes="$(printf '%s' "${str}" | wc -c 2>/dev/null | tr -cd '0-9')"
if [ -z "${nbytes}" ] || [ "${nbytes}" -le 0 ]; then
printf '%s' "${str}"
return 0
fi
win=4
if [ "${nbytes}" -lt 4 ]; then
win="${nbytes}"
fi
# Last <win> bytes as decimal values, oldest first; a UTF-8 character is
# at most 4 bytes, so the window always covers the trailing character.
# shellcheck disable=SC2046
set -- $(printf '%s' "${str}" | tail -c "${win}" | od -An -tu1 | tr '\n' ' ')
last=""; prev1=""; prev2=""; prev3=""
case $# in
1) last="$1" ;;
2) last="$2"; prev1="$1" ;;
3) last="$3"; prev1="$2"; prev2="$1" ;;
4) last="$4"; prev1="$3"; prev2="$2"; prev3="$1" ;;
*) printf '%s' "${str}"; return 0 ;;
esac
cont=0
lead=""
for b in "${last}" "${prev1}" "${prev2}" "${prev3}"; do
if [ -z "${b}" ]; then
break
fi
if [ "${b}" -ge 128 ] && [ "${b}" -le 191 ]; then
cont=$((cont + 1))
else
lead="${b}"
break
fi
done
have=$((cont + 1))
strip=0
if [ -z "${lead}" ]; then
# 4+ trailing continuation bytes: invalid before truncation, keep.
strip=0
elif [ "${lead}" -lt 128 ]; then
# Stray continuations after ASCII: invalid before truncation.
strip="${cont}"
elif [ "${lead}" -ge 194 ] && [ "${lead}" -le 223 ]; then
if [ "${have}" -lt 2 ]; then strip="${have}"; fi
elif [ "${lead}" -ge 224 ] && [ "${lead}" -le 239 ]; then
if [ "${have}" -lt 3 ]; then strip="${have}"; fi
elif [ "${lead}" -ge 240 ] && [ "${lead}" -le 244 ]; then
if [ "${have}" -lt 4 ]; then strip="${have}"; fi
else
# 0xC0, 0xC1, 0xF5-0xFF are never valid UTF-8 lead bytes.
strip="${have}"
fi
if [ "${strip}" -le 0 ]; then
printf '%s' "${str}"
return 0
fi
keep=$((nbytes - strip))
if [ "${keep}" -le 0 ]; then
return 0
fi
printf '%s' "${str}" | dd bs=1 count="${keep}" 2>/dev/null
return 0
}
# Largest numeric tick already present across every ledger-*.jsonl in the dir.
# Greps the "tick":N field with sed (no jq), sorts numerically, takes the max.
# Missing/garbage files contribute nothing.
max_tick_in_dir() {
dir="$1"
max=0
for f in "${dir}"/ledger-*.jsonl; do
[ -f "${f}" ] || continue
# Extract every "tick":<digits> value, one per line.
ticks="$(sed -n 's/.*"tick"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "${f}" 2>/dev/null)"
for t in ${ticks}; do
if [ "${t}" -gt "${max}" ] 2>/dev/null; then
max="${t}"
fi
done
done
printf '%s' "${max}"
}
iso_utc() {
# ISO8601 UTC, second precision. GNU/BSD date both honor -u; fall back to
# python, then a fixed epoch-zero marker that still parses as ISO8601.
out="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)"
if [ -n "${out}" ]; then printf '%s' "${out}"; return 0; fi
if command -v python3 >/dev/null 2>&1; then
out="$(python3 -c "import datetime;print(datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'))" 2>/dev/null)"
if [ -n "${out}" ]; then printf '%s' "${out}"; return 0; fi
fi
if command -v python >/dev/null 2>&1; then
out="$(python -c "import datetime;print(datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'))" 2>/dev/null)"
if [ -n "${out}" ]; then printf '%s' "${out}"; return 0; fi
fi
printf '1970-01-01T00:00:00Z'
}
EVENT="${1:-}"
case "${EVENT}" in
-h|--help|"")
usage
[ -z "${EVENT}" ] && exit 2 || exit 0
;;
esac
shift
SUMMARY="${1:-}"
if [ -z "${SUMMARY}" ]; then
printf "[ledger] missing <summary> argument.\n" >&2
usage
exit 2
fi
shift
AGENT="main"
PHASE=""
FILES_CSV=""
while [ $# -gt 0 ]; do
case "$1" in
--agent)
AGENT="${2:-}"
shift 2 || { printf "[ledger] --agent needs a value.\n" >&2; exit 2; }
;;
--phase)
PHASE="${2:-}"
shift 2 || { printf "[ledger] --phase needs a value.\n" >&2; exit 2; }
;;
--files)
FILES_CSV="${2:-}"
shift 2 || { printf "[ledger] --files needs a value.\n" >&2; exit 2; }
;;
*)
printf "[ledger] unknown option: %s\n" "$1" >&2
usage
exit 2
;;
esac
done
# Validate event against the allowlist.
valid=0
for e in ${VALID_EVENTS}; do
if [ "${EVENT}" = "${e}" ]; then valid=1; break; fi
done
if [ "${valid}" -ne 1 ]; then
printf "[ledger] invalid event '%s' (allowed: %s)\n" "${EVENT}" "${VALID_EVENTS}" >&2
exit 2
fi
AGENT="$(sanitize_agent "${AGENT}")"
# Truncate summary to 200 BEFORE escaping (200 is a source-text budget).
# GNU cut -c counts bytes and can land mid-codepoint on multibyte input;
# BSD cut -c counts characters and clips cleanly. The trim removes any
# incomplete trailing UTF-8 sequence so the JSONL line stays valid UTF-8.
SUMMARY="$(printf '%s' "${SUMMARY}" | cut -c1-200)"
SUMMARY="$(utf8_trim_incomplete "${SUMMARY}")"
PLAN_DIR="$(resolve_plan_dir)" || {
printf "[ledger-append] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan directory; nothing was written and no other plan was substituted.\n" >&2
exit 1
}
LEDGER_FILE="${PLAN_DIR}/ledger-${AGENT}.jsonl"
LOCK_FILE="${PLAN_DIR}/.ledger_lock"
TS="$(iso_utc)"
# Build the files JSON array from the comma-separated list.
FILES_JSON="[]"
if [ -n "${FILES_CSV}" ]; then
FILES_JSON="["
first=1
# Word-split on commas only.
OLD_IFS="$IFS"
IFS=','
for item in ${FILES_CSV}; do
IFS="$OLD_IFS"
[ -z "${item}" ] && { IFS=','; continue; }
esc="$(json_escape "${item}")"
if [ "${first}" -eq 1 ]; then
FILES_JSON="${FILES_JSON}\"${esc}\""
first=0
else
FILES_JSON="${FILES_JSON},\"${esc}\""
fi
IFS=','
done
IFS="$OLD_IFS"
FILES_JSON="${FILES_JSON}]"
fi
SUMMARY_ESC="$(json_escape "${SUMMARY}")"
PHASE_ESC="$(json_escape "${PHASE}")"
# Append under an advisory flock when available. The single printf write keeps
# the line atomic-enough on platforms without flock (line-buffered, <4KB).
append_line() {
tick="$(max_tick_in_dir "${PLAN_DIR}")"
tick=$((tick + 1))
printf '{"tick":%s,"ts":"%s","agent":"%s","phase":"%s","event":"%s","summary":"%s","files":%s}\n' \
"${tick}" "${TS}" "${AGENT}" "${PHASE_ESC}" "${EVENT}" "${SUMMARY_ESC}" "${FILES_JSON}" \
>> "${LEDGER_FILE}"
printf '%s' "${tick}"
}
if command -v flock >/dev/null 2>&1; then
# Compute tick AND write while holding the lock so concurrent appenders do
# not pick the same tick number. The subshell scopes fd 9 to the lock.
written_tick="$(
(
flock -w 5 9 || true
append_line
) 9>"${LOCK_FILE}" 2>/dev/null
)"
rm -f "${LOCK_FILE}" 2>/dev/null || true
else
written_tick="$(append_line)"
fi
printf "[ledger] tick %s -> %s (event=%s agent=%s)\n" \
"${written_tick:-?}" "${LEDGER_FILE}" "${EVENT}" "${AGENT}"
exit 0
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |