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/phase-status.sh

View on GitHub
#!/bin/sh
# planning-with-files: set the status of one phase in task_plan.md (v3).
#
# This is the ONLY sanctioned concurrent-safe writer of task_plan.md status
# lines. The orchestrator owns task_plan.md; workers NEVER edit it directly.
# All status edits go through this read-modify-write under the portable
# <plan-dir>/.pwf-locks/phase-status.lock namespace. Lock ownership is the
# atomic no-clobber creation of its .owner file; the directory's mkdir exit
# status is only provisional because some Windows-native implementations can
# report success to two simultaneous creators. The plan rewrite still uses an
# atomic temp-file + mv swap so a torn write can never leave a half-rewritten
# plan on disk (architecture C4).
#
# Note: editing task_plan.md changes its SHA, so the orchestrator must
# re-attest at phase boundaries (see attest-plan.sh).
#
# 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 ./task_plan.md
#
# Usage:
#   sh scripts/phase-status.sh <phase-number> <pending|in_progress|complete>
#
# Exits 1 with a message if the phase does not exist or the status is invalid.

set -u

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
RESOLVER="${SCRIPT_DIR}/resolve-plan-dir.sh"

usage() {
    printf "Usage: %s <phase-number> <pending|in_progress|complete>\n" "$0" >&2
}

resolve_plan_file() {
    plan_dir=""
    if [ -f "${RESOLVER}" ]; then
        plan_dir="$(sh "${RESOLVER}" 2>/dev/null)"
    fi
    if [ -n "${plan_dir}" ] && [ -f "${plan_dir}/task_plan.md" ]; then
        printf "%s\n" "${plan_dir}/task_plan.md"
        return 0
    fi
    # Explicit selectors are bindings, not hints (issue #237). This script
    # WRITES a phase status into the plan it picks, so a cwd fallback after a
    # rejected selector edits a different plan than the operator named.
    if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
        return 1
    fi
    if [ -f "./task_plan.md" ]; then
        printf "%s\n" "./task_plan.md"
        return 0
    fi
    return 1
}

PHASE_NUM="${1:-}"
NEW_STATUS="${2:-}"

if [ -z "${PHASE_NUM}" ] || [ -z "${NEW_STATUS}" ]; then
    usage
    exit 1
fi

# Validate phase number is a positive integer.
case "${PHASE_NUM}" in
    ''|*[!0-9]*)
        printf "[phase-status] phase number must be a positive integer, got '%s'.\n" "${PHASE_NUM}" >&2
        exit 1
        ;;
esac

# Validate status value against the allowlist.
case "${NEW_STATUS}" in
    pending|in_progress|complete) : ;;
    *)
        printf "[phase-status] invalid status '%s' (allowed: pending, in_progress, complete).\n" "${NEW_STATUS}" >&2
        exit 1
        ;;
esac

PLAN_FILE="$(resolve_plan_file)" || {
    if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
        printf "[phase-status] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan; nothing was written and no other plan was substituted.\n" >&2
    else
        printf "[phase-status] No task_plan.md found. Create a plan first.\n" >&2
    fi
    exit 1
}

PLAN_DIR="$(dirname "${PLAN_FILE}")"
LOCK_ROOT="${PLAN_DIR}/.pwf-locks"
LOCK_DIR="${LOCK_ROOT}/phase-status.lock"
LOCK_TOKEN=""
LOCK_ACQUIRED=0

release_lock() {
    if [ "${LOCK_ACQUIRED}" -ne 1 ] || [ -z "${LOCK_TOKEN}" ]; then
        return 0
    fi
    owner_file="${LOCK_DIR}/.owner"
    owner_value="$(cat "${owner_file}" 2>/dev/null || true)"
    if [ "${owner_value}" = "${LOCK_TOKEN}" ]; then
        rm -f "${owner_file}" 2>/dev/null || true
        rmdir "${LOCK_DIR}" 2>/dev/null || true
    fi
    LOCK_ACQUIRED=0
}

claim_lock_owner() {
    owner_file="${LOCK_DIR}/.owner"
    # POSIX noclobber makes this redirection an exclusive create. This is the
    # actual ownership decision: a Windows-native mkdir may report success
    # after another process won the directory-creation race (issue #281).
    if (
        umask 077
        set -C
        printf '%s\n' "${LOCK_TOKEN}" > "${owner_file}"
    ) 2>/dev/null; then
        LOCK_ACQUIRED=1
        return 0
    fi
    return 1
}

acquire_lock() {
    mkdir -p "${LOCK_ROOT}" 2>/dev/null || {
        printf "[phase-status] Cannot create lock root %s.\n" "${LOCK_ROOT}" >&2
        return 1
    }
    LOCK_TOKEN="phase-status-$$-$(date +%s 2>/dev/null || printf 0)"
    started_at="$(date +%s 2>/dev/null || printf 0)"
    attempts=0
    while :; do
        # Directory creation is intentionally idempotent. The exclusive owner
        # file below, not this external utility's exit status, grants the lock.
        mkdir "${LOCK_DIR}" 2>/dev/null || true
        if [ -d "${LOCK_DIR}" ] && claim_lock_owner; then
            return 0
        fi
        attempts=$((attempts + 1))
        now="$(date +%s 2>/dev/null || printf 0)"
        if { [ "${started_at}" -gt 0 ] 2>/dev/null \
                && [ $((now - started_at)) -ge 5 ]; } \
            || [ "${attempts}" -ge 50 ]; then
            printf "[phase-status] Timed out waiting for lock %s. No plan changes were made.\n" "${LOCK_DIR}" >&2
            return 75
        fi
        sleep 0.1
    done
}

trap 'release_lock' EXIT
trap 'release_lock; exit 1' HUP INT TERM

acquire_lock
lock_rc=$?
if [ "${lock_rc}" -ne 0 ]; then
    exit "${lock_rc}"
fi

# Confirm the phase heading exists while holding the same lock as the rewrite.
if ! grep -q "### Phase ${PHASE_NUM}\b" "${PLAN_FILE}" 2>/dev/null; then
    # Fall back to a looser match for headings like "### Phase 1:" where \b may
    # not be honored by a minimal grep.
    if ! grep -Eq "^### Phase ${PHASE_NUM}([^0-9]|$)" "${PLAN_FILE}" 2>/dev/null; then
        printf "[phase-status] Phase %s not found in %s.\n" "${PHASE_NUM}" "${PLAN_FILE}" >&2
        exit 1
    fi
fi

# Rewrite only the FIRST "**Status:**" line that follows the "### Phase N"
# heading. awk tracks whether we are inside the target phase block; once we
# rewrite its status line we stop matching so later phases are untouched.
rewrite() {
    src="$1"
    dst="$2"
    awk -v target="${PHASE_NUM}" -v newstatus="${NEW_STATUS}" '
        BEGIN { in_block = 0; done = 0 }
        {
            line = $0
            if (line ~ /^### Phase /) {
                # Extract the phase number right after "### Phase ".
                rest = line
                sub(/^### Phase /, "", rest)
                num = rest
                sub(/[^0-9].*$/, "", num)
                if (num == target && done == 0) {
                    in_block = 1
                } else {
                    in_block = 0
                }
            } else if (in_block == 1 && done == 0 && line ~ /\*\*Status:\*\*/) {
                # Preserve leading whitespace/bullet before "**Status:**".
                prefix = line
                sub(/\*\*Status:\*\*.*$/, "", prefix)
                line = prefix "**Status:** " newstatus
                in_block = 0
                done = 1
            }
            print line
        }
        END { if (done == 0) exit 3 }
    ' "${src}" > "${dst}"
}

TMP_FILE="${PLAN_FILE}.tmp.$$"

do_write() {
    if ! rewrite "${PLAN_FILE}" "${TMP_FILE}"; then
        rm -f "${TMP_FILE}" 2>/dev/null
        printf "[phase-status] No **Status:** line found for Phase %s.\n" "${PHASE_NUM}" >&2
        return 1
    fi
    mv -f "${TMP_FILE}" "${PLAN_FILE}"
    return 0
}

rc=0
do_write || rc=$?

if [ "${rc}" -ne 0 ]; then
    rm -f "${TMP_FILE}" 2>/dev/null
    exit 1
fi

printf "[phase-status] Phase %s -> %s in %s\n" "${PHASE_NUM}" "${NEW_STATUS}" "${PLAN_FILE}"
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