OthmanAdi/planning-with-files / .factory/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/init-session.ps1
View on GitHub# Initialize planning files for a new session
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# .\init-session.ps1 -PlanDir # isolated plan with generated slug
# .\init-session.ps1 -Autonomous # v3 autonomous mode (opt-in)
# .\init-session.ps1 -Gated # v3 gated mode (opt-in, implies autonomous)
# Templates: default, analytics
#
# v3 modes (opt-in): -Autonomous / -Gated write a .mode marker next to the plan,
# reset the .stop_blocks gate counter, clear any stale gate ledger, write a fresh
# 16-hex nonce for delimiter framing, and auto-attest the plan. With NO v3 switch
# and no .mode file, behavior is byte-equivalent to v2.43.0.
# Initialize planning files for a new session: creates task_plan.md, findings.md
# and progress.md. Use -Help / -h / -? to print usage without creating files.
# Unknown dash-prefixed switches are refused.
#
# Plain param binding, with no [CmdletBinding()] and no comment-based help
# block. Either one makes the host claim -? before this script runs, and a
# native Windows PowerShell 5.1 -File call then exits 0 with no output at all
# (#357). The usage text below replaces what Get-Help used to render.
param(
[Alias('h', '?')]
[switch]$Help,
[string]$ProjectName = "project",
[string]$Template = "default",
[switch]$PlanDir,
[switch]$Autonomous,
[switch]$Gated
)
function Show-InitSessionUsage {
@"
Usage: .\init-session.ps1 [-Template TYPE] [project-name]
.\init-session.ps1 -PlanDir
.\init-session.ps1 -Autonomous
.\init-session.ps1 -Gated
Options:
-Template TYPE Use the default or analytics template.
-PlanDir Create an isolated plan directory without a name.
-Autonomous Enable autonomous mode and plan attestation.
-Gated Enable autonomous mode with the completion gate.
-Help, -h, -? Print this help and exit without changing files.
"@
}
# Without [CmdletBinding()] the host no longer rejects unknown dash switches, so
# refuse them here. The shell twin exits non-zero on the same input.
$Unbound = @($MyInvocation.UnboundArguments)
if ($Unbound.Count -gt 0) {
$Extra = $Unbound -join ' '
[Console]::Error.WriteLine("Unknown switch: $Extra")
[Console]::Error.WriteLine((Show-InitSessionUsage))
exit 1
}
if ($Help) {
Show-InitSessionUsage
exit 0
}
# Windows PowerShell 5.1 can silently relocate a -File invocation when the
# inherited cwd contains wildcard characters such as [ or ]. Recover the
# physical cwd for a direct invocation before any project-relative paths are
# resolved.
if ($PSVersionTable.PSVersion.Major -eq 5 -and
[System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
$processArgs = [Environment]::GetCommandLineArgs()
for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
if ($processArgs[$index] -ieq '-File') {
$entryScript = $processArgs[$index + 1]
if (-not [IO.Path]::IsPathRooted($entryScript)) {
$entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
}
if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
Set-Location -LiteralPath ([Environment]::CurrentDirectory)
}
break
}
}
}
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker.
$Mode = ""
if ($Gated) {
$Mode = "gated"
} elseif ($Autonomous) {
$Mode = "autonomous"
}
# Resolve template directory (skill root is one level up from scripts/)
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
$SkillRoot = Split-Path -Parent $ScriptDir
$TemplateDir = Join-Path $SkillRoot "templates"
function Get-Nonce {
# 16 hex chars for the plan-data delimiter framing (security strand rec 8).
$bytes = New-Object 'System.Byte[]' 8
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
}
function Get-PlanSlug([string]$Name) {
# -creplace: the case-insensitive -replace lets letters that .NET folds to
# ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
$slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
$slug = $slug -creplace '-{2,}', '-'
$slug = $slug.Trim('-')
if ($slug.Length -gt 40) {
$slug = $slug.Substring(0, 40).TrimEnd('-')
}
# The resolvers and the selector only accept ASCII plan ids.
if ($slug -cnotmatch '^[a-z0-9-]*$') {
return ""
}
return $slug
}
function Get-ShortId {
return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
}
function Get-InheritedMode([string]$CurrentMode) {
$RootModePath = Join-Path (Get-Location).Path ".mode"
if (-not (Test-Path -LiteralPath $RootModePath)) {
return $CurrentMode
}
if ($CurrentMode -eq "gated") {
return $CurrentMode
}
$RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
# Case-sensitive like inherit_root_mode in init-session.sh and the injector.
if ($RootMode -cmatch 'gate') {
return "gated"
}
if ($RootMode -cmatch 'autonomous') {
return "autonomous"
}
return $CurrentMode
}
function Format-AttestationFailureReason {
param([object[]]$Output, [string]$Fallback)
$Reason = @(
$Output |
ForEach-Object {
if ($null -ne $_) { ($_.ToString()).Trim() }
} |
Where-Object { $_ }
) -join " "
$Reason = ($Reason -replace '\s+', ' ').Trim()
if ([string]::IsNullOrWhiteSpace($Reason)) {
return $Fallback
}
if ($Reason.Length -gt 300) {
return ($Reason.Substring(0, 297) + "...")
}
return $Reason
}
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
Write-Host "Unknown template: $Template (available: default, analytics). Using default."
$Template = "default"
}
# Match init-session.sh: zero args (or an empty name) preserve legacy root
# mode. A positional project name or -PlanDir creates an isolated
# .planning/<date>-<slug>/ plan.
$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
$UsePlanDir = $PlanDir -or $NamedPlan
if ($UsePlanDir) {
$PlanningRoot = Join-Path (Get-Location).Path ".planning"
# Match init-session.sh: set-active-plan.ps1 owns every write to the
# shared pointer, so a named plan cannot be created without it.
$PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
exit 1
}
New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. A
# script that returns without exit leaves $LASTEXITCODE alone, so reset
# it first and treat a thrown error as a failure too.
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) {
Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
exit 1
}
if ($NamedPlan) {
$Slug = Get-PlanSlug $ProjectName
} else {
$Slug = ""
$ProjectName = "untitled"
}
if ([string]::IsNullOrEmpty($Slug)) {
$Slug = "untitled-$(Get-ShortId)"
}
$BaseId = "$DATE-$Slug"
$PlanId = $BaseId
$Counter = 2
while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
$PlanId = "$BaseId-$Counter"
$Counter++
}
$TargetDir = Join-Path $PlanningRoot $PlanId
New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
}
$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
$FindingsPath = Join-Path $TargetDir "findings.md"
$ProgressPath = Join-Path $TargetDir "progress.md"
if ($UsePlanDir) {
$TaskPlanDisplay = $TaskPlanPath
$FindingsDisplay = $FindingsPath
$ProgressDisplay = $ProgressPath
} else {
$TaskPlanDisplay = "task_plan.md"
$FindingsDisplay = "findings.md"
$ProgressDisplay = "progress.md"
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
try {
# Create task_plan.md if it doesn't exist
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
} else {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Next Step
[The single next action. Update whenever phase status changes.]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $TaskPlanDisplay"
} else {
Write-Host "$TaskPlanDisplay already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
} else {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $FindingsDisplay"
} else {
Write-Host "$FindingsDisplay already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path -LiteralPath $ProgressPath)) {
if ($Template -eq "analytics") {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Data Discovery
- **Started:** $DATE
### Actions Taken
-
### Query Log
| Query | Result Summary | Interpretation |
|-------|---------------|----------------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
} else {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
}
Write-Host "Created $ProgressDisplay"
} else {
Write-Host "$ProgressDisplay already exists, skipping"
}
} catch {
Write-Error "Error: could not initialize planning files in '$TargetDir': $($_.Exception.Message)"
exit 1
}
if ($UsePlanDir) {
# Activate the named plan only after all three planning files are ready.
# This matches init-session.sh and prevents a failed initialization from
# leaving .active_plan pointed at a partial plan directory.
$pointerSet = $false
for ($attempt = 1; $attempt -le 5; $attempt++) {
$global:LASTEXITCODE = 0
try {
$selectorResult = & $PlanSelector $PlanId 2>&1
} catch {
$selectorResult = $_
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -eq 0) {
$pointerSet = $true
break
}
# Another writer can replace the pointer between the selector's
# Get-Item and final-path check. Retry only that transient result.
$transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and
$selectorResult.Exception.Message -in @(
'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement',
'Error: the active plan pointer must be a regular file within the project.'
)
if ($attempt -eq 5 -or -not $transientPointerRace) {
break
}
Start-Sleep -Milliseconds 50
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) { break }
}
if (-not $pointerSet) {
Write-Error "Error: could not safely update the active plan pointer at $(Join-Path $PlanningRoot '.active_plan')."
exit 1
}
}
Write-Host ""
Write-Host "Planning files initialized!"
if ($UsePlanDir) {
Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
Write-Host "Pin this terminal to the plan for parallel sessions:"
Write-Host " `$env:PLAN_ID='$PlanId'"
} else {
Write-Host "Files: task_plan.md, findings.md, progress.md"
}
# v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
# selected plan; root mode therefore retains the legacy project-root behavior.
if ($Mode -ne "") {
$PlanDirPwf = $TargetDir
# (a) reset gate block counter, drop stale gate ledger.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
$StaleLedger = Join-Path $PlanDirPwf ".gate_last_ledger"
if (Test-Path -LiteralPath $StaleLedger) { Remove-Item -LiteralPath $StaleLedger -Force }
# (b) fresh 16-hex nonce for delimiter framing.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".nonce") -Value (Get-Nonce) -NoNewline -Encoding ascii
# mode marker. gated implies autonomous, so it carries both tokens.
if ($Mode -eq "gated") {
$MarkerText = "autonomous gate"
} else {
$MarkerText = "autonomous"
}
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Slug mode binds PWF_PLAN_ROOT and PLAN_ID to the plan
# we just created so an inherited pin or slug cannot redirect attestation
# to another project or plan (#261, #237). Root mode clears both instead:
# the attester only falls back to the legacy ./task_plan.md when no
# selector is set, and a bound pin would make it refuse the root plan.
$AttestationSucceeded = $false
$AttestationCommand = "attest-plan"
$AttestationReason = "task_plan.md was not available for attestation"
$PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
if (Test-Path -LiteralPath $PlanFilePwf -PathType Leaf) {
$HadPlanId = Test-Path Env:PLAN_ID
$PreviousPlanId = $env:PLAN_ID
$HadPlanRoot = Test-Path Env:PWF_PLAN_ROOT
$PreviousPlanRoot = $env:PWF_PLAN_ROOT
try {
if ($UsePlanDir) {
$env:PWF_PLAN_ROOT = (Get-Location).Path
$env:PLAN_ID = $PlanId
} else {
Remove-Item Env:PWF_PLAN_ROOT -ErrorAction SilentlyContinue
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
# A called script can return without changing $LASTEXITCODE, so
# clear the inherited value before every attempt. Both a non-zero
# status and a terminating exception mean the plan is not attested.
$global:LASTEXITCODE = 0
$AttestOutput = @()
$IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if ($IsWindowsHost) {
$AttestationCommand = "attest-plan.ps1"
$AttestPs1 = Join-Path $ScriptDir $AttestationCommand
if (Test-Path -LiteralPath $AttestPs1 -PathType Leaf) {
$AttestOutput = @(& $AttestPs1 2>&1)
$AttestExitCode = $LASTEXITCODE
if ($AttestExitCode -eq 0) {
$AttestationSucceeded = $true
$AttestationReason = ""
} else {
$AttestationReason = Format-AttestationFailureReason `
-Output $AttestOutput `
-Fallback "$AttestationCommand exited with code $AttestExitCode"
}
} else {
$AttestationReason = "$AttestationCommand was not found beside init-session.ps1"
}
} else {
$AttestationCommand = "attest-plan.sh"
$AttestSh = Join-Path $ScriptDir $AttestationCommand
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh -PathType Leaf)) {
$AttestOutput = @(& $Sh.Path $AttestSh 2>&1)
$AttestExitCode = $LASTEXITCODE
if ($AttestExitCode -eq 0) {
$AttestationSucceeded = $true
$AttestationReason = ""
} else {
$AttestationReason = Format-AttestationFailureReason `
-Output $AttestOutput `
-Fallback "$AttestationCommand exited with code $AttestExitCode"
}
} elseif (-not $Sh) {
$AttestationReason = "sh was not found; $AttestationCommand could not run"
} else {
$AttestationReason = "$AttestationCommand was not found beside init-session.ps1"
}
}
} catch {
$AttestationReason = Format-AttestationFailureReason `
-Output @($_) `
-Fallback "$AttestationCommand failed"
} finally {
if ($HadPlanId) {
$env:PLAN_ID = $PreviousPlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
if ($HadPlanRoot) {
$env:PWF_PLAN_ROOT = $PreviousPlanRoot
} else {
Remove-Item Env:PWF_PLAN_ROOT -ErrorAction SilentlyContinue
}
}
}
if ($AttestationSucceeded) {
Write-Host "Mode: $MarkerText (attested, gate counter reset)"
} else {
Write-Host "Mode: $MarkerText (NOT attested: $AttestationReason; run $AttestationCommand before the first hook fire)"
}
}
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 | Verified | 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 |