Skip to content

OthmanAdi/planning-with-files / skills/i18n/planning-with-files-ar

planning-with-files-ar

Verified

تخطيط مستمر قائم على الملفات لعمل وكلاء الذكاء الاصطناعي متعدد الخطوات. يحتفظ بملفات task_plan.md و findings.md و progress.md على القرص، وتحقن خطافات دورة الحياة سياق التخطيط المحدد للمشروع. تقرأ الاستعادة التلقائية ملفات تخطيط المشروع فقط. يمكن للأمر الصريح session-catchup.py --metadata فحص بيانات وصفية لجلسات الوكيل المحلية التابعة للمشروع نفسه، بينما قد يصدر --replay مقتطفات محدودة مؤطرة بقيمة nonce. يمكن للوضع المحكوم الاختياري طلب المتابعة فقط عندما يدعمه المضيف، ولا ينفذ أبدًا أوامر معلنة في Markdown. لا تتضمن المهارة مسارًا لرفع البيانات عبر الشبكة. تُستخدم للبحث أو العمل الذي يحتاج إلى 5 استدعاءات أدوات أو أكثر.

scripts/phase-status.ps1

View on GitHub
#requires -Version 5.0
<#
.SYNOPSIS
    Set the status of one phase in task_plan.md (PowerShell mirror, v3).

.DESCRIPTION
    The ONLY sanctioned concurrent-safe writer of task_plan.md status lines. The
    orchestrator owns task_plan.md; workers NEVER edit it directly. The edit is
    a read-modify-write under the portable
    <plan-dir>\.pwf-locks\phase-status.lock namespace. Ownership is granted by
    atomically creating its .owner file, rather than trusting an external mkdir
    exit status. The plan rewrite uses an atomic temp-file + move swap so a torn
    write can never leave a half-rewritten plan on disk (architecture C4).

    Editing task_plan.md changes its SHA, so the orchestrator must re-attest at
    phase boundaries (see attest-plan.ps1).

    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 .\task_plan.md

    Exits 1 with a message if the phase does not exist or the status is invalid.

.PARAMETER Phase
    Phase number (positive integer).

.PARAMETER Status
    New status: pending, in_progress, or complete.
#>
[CmdletBinding()]
param(
    [Parameter(Mandatory = $true, Position = 0)]
    [string] $Phase,

    [Parameter(Mandatory = $true, Position = 1)]
    [string] $Status
)

$ErrorActionPreference = "Stop"

function Resolve-PlanFile {
    $planRoot = Join-Path (Get-Location) ".planning"

    # A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that
    # names no plan directory stops resolution instead of falling through to
    # .active_plan and newest-by-mtime: this script reports phase state, and
    # answering a mistyped pin with a DIFFERENT plan's phases is the same
    # wrong-plan harm that let a typo attest the wrong file.
    if ($env:PLAN_ID) {
        $candidate = Join-Path $planRoot $env:PLAN_ID
        $planFile  = Join-Path $candidate "task_plan.md"
        if (Test-Path -LiteralPath $planFile) { return (Resolve-Path -LiteralPath $planFile).Path }
        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
            $planFile  = Join-Path $candidate "task_plan.md"
            if (Test-Path -LiteralPath $planFile) { return (Resolve-Path -LiteralPath $planFile).Path }
        }
    }

    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 (Resolve-Path -LiteralPath (Join-Path $newest.FullName "task_plan.md")).Path
        }
    }

    $legacy = Join-Path (Get-Location) "task_plan.md"
    if (Test-Path -LiteralPath $legacy) {
        return (Resolve-Path -LiteralPath $legacy).Path
    }

    return $null
}

function Enter-PwfDirectoryLock {
    param(
        [string] $LockRoot,
        [string] $LockDir
    )

    try {
        [void][System.IO.Directory]::CreateDirectory($LockRoot)
    } catch {
        Write-Error ("[phase-status] Cannot create lock root " + $LockRoot + ": " + $_.Exception.Message)
        return $null
    }

    $token = "phase-status-" + $PID + "-" + [Guid]::NewGuid().ToString("N")
    $ownerFile = Join-Path $LockDir ".owner"
    $utf8NoBom = New-Object System.Text.UTF8Encoding($false)

    $wait = [Diagnostics.Stopwatch]::StartNew()
    while ($wait.Elapsed.TotalSeconds -lt 5) {
        try {
            [void][System.IO.Directory]::CreateDirectory($LockDir)
        } catch {
            Start-Sleep -Milliseconds 100
            continue
        }

        $stream = $null
        $createdOwner = $false
        $claimed = $false
        try {
            # FileMode.CreateNew is the cross-runtime ownership decision. It
            # fails atomically when either the shell or PowerShell writer has
            # already claimed .owner, even if both observed mkdir success.
            $stream = [System.IO.File]::Open(
                $ownerFile,
                [System.IO.FileMode]::CreateNew,
                [System.IO.FileAccess]::Write,
                [System.IO.FileShare]::None
            )
            $createdOwner = $true
            $bytes = $utf8NoBom.GetBytes($token + "`n")
            $stream.Write($bytes, 0, $bytes.Length)
            $stream.Flush()
            $claimed = $true
            return [PSCustomObject]@{
                Directory = $LockDir
                OwnerFile = $ownerFile
                Token = $token
            }
        } catch {
            # Existing ownership is the normal contention path. Other failures
            # remain fail-closed and are retried only within the bounded wait.
        } finally {
            if ($stream) {
                $stream.Dispose()
            }
            if ($createdOwner -and -not $claimed) {
                try {
                    if ([System.IO.File]::Exists($ownerFile)) {
                        $ownerValue = [System.IO.File]::ReadAllText($ownerFile).Trim()
                        if ([string]::Equals($ownerValue, $token, [StringComparison]::Ordinal)) {
                            [System.IO.File]::Delete($ownerFile)
                        }
                    }
                } catch {
                    # Leave any owner file we cannot prove is still ours intact.
                }
            }
        }
        Start-Sleep -Milliseconds 100
    }

    return $null
}

function Exit-PwfDirectoryLock {
    param($Lock)
    if (-not $Lock) { return }
    try {
        if (-not [System.IO.File]::Exists($Lock.OwnerFile)) { return }
        $ownerValue = [System.IO.File]::ReadAllText($Lock.OwnerFile).Trim()
        if (-not [string]::Equals($ownerValue, $Lock.Token, [StringComparison]::Ordinal)) { return }
        [System.IO.File]::Delete($Lock.OwnerFile)
        [System.IO.Directory]::Delete($Lock.Directory, $false)
    } catch {
        # Cleanup is best-effort and never removes a lock with another owner.
    }
}

# Validate phase number is a positive integer.
if ($Phase -notmatch '^[0-9]+$') {
    Write-Error ("[phase-status] phase number must be a positive integer, got '" + $Phase + "'.")
    exit 1
}

# Validate status value against the allowlist.
$validStatus = @("pending", "in_progress", "complete")
if ($validStatus -notcontains $Status) {
    Write-Error ("[phase-status] invalid status '" + $Status + "' (allowed: pending, in_progress, complete).")
    exit 1
}

$planFile = Resolve-PlanFile
if (-not $planFile) {
    if ($env:PLAN_ID) {
        Write-Error "[phase-status] PLAN_ID names no plan directory under .planning; nothing was written and no other plan was substituted."
    } else {
        Write-Error "[phase-status] No task_plan.md found. Create a plan first."
    }
    exit 1
}

$planDir  = Split-Path -Parent $planFile
$lockRoot = Join-Path $planDir ".pwf-locks"
$lockDir  = Join-Path $lockRoot "phase-status.lock"

# Exclusive .owner creation is the common lock primitive used by both the sh
# and PowerShell implementations. Failure to acquire within about five seconds
# is fail-closed: no plan read/rewrite is attempted.
$lock = Enter-PwfDirectoryLock -LockRoot $lockRoot -LockDir $lockDir
if (-not $lock) {
    Write-Error ("[phase-status] Timed out waiting for lock " + $lockDir + ". No plan changes were made.")
    exit 75
}

$tmpFile = $planFile + ".tmp." + $PID
$rc = 0
try {
    $lines = Get-Content -LiteralPath $planFile

    # Confirm the phase heading exists.
    $headingRe = '^### Phase ' + $Phase + '([^0-9]|$)'
    if (-not ($lines | Where-Object { $_ -match $headingRe })) {
        Write-Error ("[phase-status] Phase " + $Phase + " not found in " + $planFile + ".")
        $rc = 1
    } else {
        $inBlock = $false
        $done = $false
        $out = New-Object System.Collections.Generic.List[string]
        foreach ($line in $lines) {
            $emit = $line
            if ($line -match '^### Phase ') {
                $rest = $line -replace '^### Phase ', ''
                $num = $rest -replace '[^0-9].*$', ''
                if (($num -eq $Phase) -and (-not $done)) {
                    $inBlock = $true
                } else {
                    $inBlock = $false
                }
            } elseif ($inBlock -and (-not $done) -and ($line -match '\*\*Status:\*\*')) {
                $prefix = $line -replace '\*\*Status:\*\*.*$', ''
                $emit = $prefix + '**Status:** ' + $Status
                $inBlock = $false
                $done = $true
            }
            $out.Add($emit)
        }

        if (-not $done) {
            Write-Error ("[phase-status] No **Status:** line found for Phase " + $Phase + ".")
            $rc = 1
        } else {
            # Atomic-enough swap: write temp, then move over the target.
            # Write BOM-less UTF-8 (platform-major): Set-Content -Encoding utf8 on
            # Windows PowerShell 5.1 prepends a UTF-8 BOM (EF BB BF). The temp file
            # then replaces task_plan.md, so every phase-status call from PS 5.1
            # changes the file's leading bytes. If the plan was created on Linux or
            # macOS (no BOM), the stored attestation SHA-256 no longer matches and
            # inject-plan.sh blocks all further injection as [PLAN TAMPERED]. A
            # UTF8Encoding constructed with $false emits no BOM on every PS version.
            $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
            [System.IO.File]::WriteAllLines($tmpFile, $out, $utf8NoBom)
            Move-Item -LiteralPath $tmpFile -Destination $planFile -Force
        }
    }
} catch {
    Write-Error ("[phase-status] " + $_.Exception.Message)
    $rc = 1
} finally {
    Exit-PwfDirectoryLock -Lock $lock
    if (Test-Path -LiteralPath $tmpFile) { Remove-Item -LiteralPath $tmpFile -Force -ErrorAction SilentlyContinue }
}

if ($rc -ne 0) { exit 1 }

Write-Output ("[phase-status] Phase " + $Phase + " -> " + $Status + " in " + $planFile)
exit 0
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall