Skip to content

OthmanAdi/planning-with-files / .pi/skills/planning-with-files

planning-with-files

Flagged

Persistent 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.

FileKindSize
LICENSEother1.0 KB
README.mdmarkdown116.4 KB
SKILL.mdskill md41.0 KB
examples.mdmarkdown4.4 KB
extensions/planning-with-files/README.mdmarkdown2.9 KB
extensions/planning-with-files/__tests__/attestation.test.tsscript8.8 KB
extensions/planning-with-files/__tests__/phase-counts.test.tsscript1.5 KB
extensions/planning-with-files/__tests__/plan-anchor.test.tsscript10.7 KB
extensions/planning-with-files/__tests__/runtime.test.tsscript36.3 KB
extensions/planning-with-files/attestation.tsscript1.3 KB
extensions/planning-with-files/constants.tsscript1.5 KB
extensions/planning-with-files/index.tsscript211 B
extensions/planning-with-files/package-lock.jsonmanifest120.5 KB
extensions/planning-with-files/package.jsonmanifest337 B
extensions/planning-with-files/plan.tsscript13.5 KB
extensions/planning-with-files/runtime.tsscript29.9 KB
package.jsonmanifest1.5 KB
plan-inventory.mdmarkdown9.3 KB
reference.mdmarkdown8.3 KB
scripts/attest-plan.ps1script27.4 KB
scripts/attest-plan.shscript27.4 KB
scripts/check-complete.ps1script12.8 KB
scripts/check-complete.shexecutablescript13.6 KB
scripts/gate-stop.shscript1.4 KB
scripts/init-session.ps1script19.5 KB
scripts/init-session.shexecutablescript15.4 KB
scripts/inject-plan.pyscript66.1 KB
scripts/inject-plan.shscript63.5 KB
scripts/ledger-append.ps1script6.7 KB
scripts/ledger-append.shscript11.9 KB
scripts/ledger-summary.ps1script6.7 KB
scripts/ledger-summary.shscript7.8 KB
scripts/phase-status.ps1script10.2 KB
scripts/phase-status.shscript7.4 KB
scripts/plan-doctor.shscript9.0 KB
scripts/resolve-plan-dir.ps1script11.5 KB
scripts/resolve-plan-dir.shscript15.3 KB
scripts/session-catchup.pyexecutablescript36.4 KB
scripts/set-active-plan.ps1executablescript42.7 KB
scripts/set-active-plan.shexecutablescript38.6 KB
scripts/skill-hook.shexecutablescript19.3 KB
scripts/verify-shell-line-endings.mjsscript1.3 KB
templates/analytics_findings.mdmarkdown1.8 KB
templates/analytics_task_plan.mdmarkdown2.5 KB
templates/findings.mdmarkdown1.1 KB
templates/loop.mdmarkdown2.1 KB
templates/progress.mdmarkdown1.5 KB
templates/task_plan.mdmarkdown2.2 KB

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
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall