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/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
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