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.ps1
View on GitHub#requires -Version 5.0
<#
.SYNOPSIS
Append one structured entry to the run-ledger (PowerShell mirror, v3).
.DESCRIPTION
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 (matches resolve-plan-dir.ps1):
1. $env:PLAN_ID -> .\.planning\$PLAN_ID\
2. .\.planning\.active_plan
3. Newest .\.planning\<dir>\ by LastWriteTime
4. Legacy: project root (ledger lands beside .\task_plan.md)
Writes ONE JSON line to <plan-dir>\ledger-<agent>.jsonl. tick = 1 + max tick
across ALL ledger-*.jsonl in the plan dir so concurrent agents share a
monotonic counter.
.PARAMETER Event
One of: progress phase_complete error gate_block attest note.
.PARAMETER Summary
Free text, truncated to 200 chars, newlines stripped.
.PARAMETER Agent
Ledger owner (default "main"); sanitized to [A-Za-z0-9_-].
.PARAMETER Phase
Phase number/name this entry concerns.
.PARAMETER Files
Comma-separated file list recorded as a JSON array.
#>
[CmdletBinding()]
param(
[Parameter(Mandatory = $true, Position = 0)]
[string] $Event,
[Parameter(Mandatory = $true, Position = 1)]
[string] $Summary,
[string] $Agent = "main",
[string] $Phase = "",
[string] $Files = ""
)
$ErrorActionPreference = "Stop"
$validEvents = @("progress", "phase_complete", "error", "gate_block", "attest", "note")
function Resolve-PlanDir {
$planRoot = Join-Path (Get-Location) ".planning"
# A set PLAN_ID is a BINDING, not a hint (issue #237). This script WRITES
# ledger rows into the directory it picks, so falling through to
# .active_plan, newest-by-mtime and finally the cwd after a mistyped pin
# files another plan's run history.
if ($env:PLAN_ID) {
$candidate = Join-Path $planRoot $env:PLAN_ID
if (Test-Path -LiteralPath $candidate -PathType Container) { return $candidate }
return $null
}
$activePointer = Join-Path $planRoot ".active_plan"
if (Test-Path -LiteralPath $activePointer) {
$planId = "$(Get-Content -LiteralPath $activePointer -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId) {
$candidate = Join-Path $planRoot $planId
if (Test-Path -LiteralPath $candidate -PathType Container) { return $candidate }
}
}
if (Test-Path -LiteralPath $planRoot -PathType Container) {
$newest = Get-ChildItem -LiteralPath $planRoot -Directory -ErrorAction SilentlyContinue |
Where-Object { -not $_.Name.StartsWith(".") } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") } |
Sort-Object LastWriteTime -Descending |
Select-Object -First 1
if ($newest) { return $newest.FullName }
}
# Legacy single-file mode: ledger lives beside .\task_plan.md at root.
return (Get-Location).Path
}
function ConvertTo-JsonString {
param([string] $Value)
$sb = New-Object System.Text.StringBuilder
foreach ($ch in $Value.ToCharArray()) {
switch ($ch) {
'"' { [void]$sb.Append('\"') }
'\' { [void]$sb.Append('\\') }
"`n" { [void]$sb.Append(' ') }
"`r" { [void]$sb.Append(' ') }
"`t" { [void]$sb.Append(' ') }
default {
if ([int]$ch -lt 32) {
[void]$sb.Append(' ')
} else {
[void]$sb.Append($ch)
}
}
}
}
return $sb.ToString()
}
function Get-MaxTick {
param([string] $Dir)
$max = 0
$pattern = '"tick"\s*:\s*(\d+)'
Get-ChildItem -LiteralPath $Dir -Filter "ledger-*.jsonl" -File -ErrorAction SilentlyContinue | ForEach-Object {
foreach ($line in (Get-Content -LiteralPath $_.FullName -ErrorAction SilentlyContinue)) {
$m = [regex]::Match($line, $pattern)
if ($m.Success) {
$t = [int]$m.Groups[1].Value
if ($t -gt $max) { $max = $t }
}
}
}
return $max
}
# Validate event against the allowlist.
if ($validEvents -notcontains $Event) {
Write-Error ("[ledger] invalid event '" + $Event + "' (allowed: " + ($validEvents -join ' ') + ")")
exit 2
}
# Sanitize agent name to [A-Za-z0-9_-]; empty result falls back to "main".
$agentClean = ($Agent -replace '[^A-Za-z0-9_-]', '')
if (-not $agentClean) { $agentClean = "main" }
# Truncate summary to the 200-character budget before escaping, matching the
# sh twin. .NET Substring counts characters, never bytes, so multibyte input
# cannot be clipped mid-codepoint here and no UTF-8 tail repair is needed.
if ($Summary.Length -gt 200) { $Summary = $Summary.Substring(0, 200) }
$planDir = Resolve-PlanDir
if (-not $planDir) {
Write-Error "[ledger-append] An explicit PLAN_ID did not resolve to a plan directory; nothing was written and no other plan was substituted."
exit 1
}
$ledgerFile = Join-Path $planDir ("ledger-" + $agentClean + ".jsonl")
$lockFile = Join-Path $planDir ".ledger_lock"
$ts = [DateTime]::UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ")
# Build the files JSON array from the comma-separated list.
$filesJson = "[]"
if ($Files) {
$parts = $Files.Split(",") | Where-Object { $_ -ne "" }
$escaped = $parts | ForEach-Object { '"' + (ConvertTo-JsonString $_) + '"' }
$filesJson = "[" + ($escaped -join ",") + "]"
}
$summaryEsc = ConvertTo-JsonString $Summary
$phaseEsc = ConvertTo-JsonString $Phase
# Acquire an exclusive lock on a sidecar so concurrent appenders do not pick
# the same tick number, then compute tick and append inside the locked window.
# Atomic append of a single <4KB line is the real guarantee; the lock just
# serializes the read-tick / write-line pair.
$fs = $null
$acquired = $false
for ($i = 0; $i -lt 50 -and -not $acquired; $i++) {
try {
$fs = [System.IO.File]::Open($lockFile, [System.IO.FileMode]::OpenOrCreate, [System.IO.FileAccess]::ReadWrite, [System.IO.FileShare]::None)
$acquired = $true
} catch {
Start-Sleep -Milliseconds 100
}
}
try {
$tick = (Get-MaxTick $planDir) + 1
$line = '{"tick":' + $tick + ',"ts":"' + $ts + '","agent":"' + $agentClean + '","phase":"' + $phaseEsc + '","event":"' + $Event + '","summary":"' + $summaryEsc + '","files":' + $filesJson + '}'
Add-Content -LiteralPath $ledgerFile -Value $line -Encoding utf8
} finally {
if ($fs) { $fs.Close(); $fs.Dispose() }
if (Test-Path -LiteralPath $lockFile) { Remove-Item -LiteralPath $lockFile -Force -ErrorAction SilentlyContinue }
}
Write-Output ("[ledger] tick " + $tick + " -> " + $ledgerFile + " (event=" + $Event + " agent=" + $agentClean + ")")
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 |