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 استدعاءات أدوات أو أكثر.

plan-inventory.md

View on GitHub
# Agent-readable plan inventory

Use this when an agent needs to find saved planning files before resuming,
reviewing or handing off a task. It is optional; ordinary skill activation and
planning do not run inventory.

Run from the project you want to inspect, using the installed skill directory:

```sh
sh "<skill-dir>/scripts/set-active-plan.sh" --list --json
sh "<skill-dir>/scripts/set-active-plan.sh" --list --json --limit 10 --offset 0
```

```powershell
& "<skill-dir>/scripts/set-active-plan.ps1" -List -Json
& "<skill-dir>/scripts/set-active-plan.ps1" -List -Json -Limit 10 -Offset 0
```

The shell helper expects `--list` first, as in `--list --json`,
`--list --archived` and `--list --json --archived`.

Existing `--list` / `-List` output remains available for humans. Both formats
inspect the current directory. `PWF_PLAN_ROOT` does not redirect inventory.
Read `scope.project_root` before using returned paths. To inspect another
project, deliberately change to that validated project directory first.

## Schema version 1

The shell command writes one UTF-8 JSON line with an LF terminator to stdout.
Started from another process with a literal `-File` argument (`pwsh -File` or
`powershell -File`), the PowerShell script also writes one UTF-8 line with an
LF terminator. Every other call form, including use inside a session,
`-Command "& ... -List -Json"`, `-f` and a positional script path, hands the
same JSON to the pipeline with every non-ASCII character escaped as `\uXXXX`,
so the text is pure ASCII and decodes identically under any console code page;
the line ending is then the host's. Inside a PowerShell session,
`& "<skill-dir>/scripts/set-active-plan.ps1" -List -Json | ConvertFrom-Json`
returns the parsed object with the real characters. No model, service or extra
runtime is required. Invalid arguments fail without selecting or changing any
plan.

| Field | Meaning |
|---|---|
| `schema_version` | `1`; independent of the skill release version |
| `scope` | Absolute inspected `project_root`, with `source: "cwd"` |
| `candidates` | Root triplet first when present, then ASCII-ordered named plans (archived plans only with `--archived`) |
| `shared_default` | `.active_plan` ID and `present`, `missing`, `dangling`, `invalid` or `excluded` state |
| `selection` | Resolver-visible process selection; not a native conversation binding |
| `host_session` | `null`; this helper cannot establish a host's conversation state |
| `archived_count` | Integer count of archived plans under `.planning/.archive/`; `0` when that directory is missing, a link or outside the project |
| `limits` | Requested `limit`/`offset`, `returned`, `truncated`, `next_offset`, and `skipped` count |
| `warnings` | Reasons for partial metadata; inspect these before treating the inventory as complete |

Each candidate contains `kind` (`root`, `named` or `archived`), `plan_id`
(`null` for root), `ownership: "unknown"`, `files`, and `phases`. Each file
entry has its absolute `path`, `status` (`readable`, `missing`, `unreadable` or
`excluded`) and `modified_at` (Unix seconds, or `null`). The inventory does not
print file bodies, derive a summary with an LLM, or decide whether a file is
obsolete.

`archived_count` counts immediate directories in `.planning/.archive/` that
have a valid plan ID, are not links and hold a regular `task_plan.md`.
`--list --json --archived` (PowerShell: `-List -Json -Archived`) lists those
plans instead of the root and named plans. The envelope, schema version,
paging, limits, warnings and `archived_count` stay the same, there is no root
candidate, and each candidate has `kind: "archived"`, its `plan_id`, and file
paths under `<project_root>/.planning/.archive/<id>/`.

`phases` includes `total`, `complete`, `in_progress`, `pending`, and `status`:
`parsed`, `empty`, `malformed`, `unavailable` or `too_large`. Counts use the
existing native phase conventions and ignore fenced examples. Empty or
malformed structure is not completion. Phase reads are limited to 256 KiB per
plan; larger files retain file metadata without a phase summary.

`selection.status` can be `selected`, `legacy_root`, `none`, `ambiguous`,
`rejected`, `outside_scope` or `unknown`. An invalid explicit pin never becomes
another plan. A pin naming another project is outside the cwd inventory.
Partial installs without a sibling resolver report selection as unknown.
Oversized pointer metadata or an excluded planning root also leaves selection
unknown (an explicit plan pin into that excluded root is rejected). A
`selected` status can name a `PLAN_ID` directory that has no `task_plan.md`,
so `selection.plan_id` is not guaranteed to appear in `candidates`. The shared
default must not be treated as the current session's assigned task.

Default output is up to 20 candidates, with a 16 KiB stdout ceiling. `limit`
accepts 1 through 100; `offset` accepts 0 through 999999. If `truncated` is
true, request `next_offset` to continue. An entry too large to fit is skipped
explicitly rather than producing broken JSON. Paging reflects the filesystem
at each invocation, so concurrent changes can alter page boundaries. A
`next_offset` is valid only for the runtime that returned it: the shell and
PowerShell routes can end pages at different entries because their byte
budgets and path escaping differ. Only immediate plan directories in
`.planning/` (or `.planning/.archive/` with `--archived`) are enumerated; no
recursive project, disk, worktree or agent-session-store scan runs. Links and
unsafe paths are excluded.

## Worker handoff

The parent can use these paths to send a worker a compact assignment:

```text
Project: <scope.project_root>
Assigned plan: <explicit selected plan ID>
Planning files: <the three files.*.path values>
Write scope: <worker-owned files or ledger>
Plan owner: <orchestrator>
```

Resolve rejected or ambiguous selection before assigning work. Inventory does
not bind a host, initialize a plan, edit a pointer, attest, archive or delete
anything. Keep the existing single-owner rule for shared summaries. File age,
reported completion and candidate discovery do not authorize cleanup.

## Archive and restore

Without `PLAN_ID`, two or more named plans make selection ambiguous and hooks
inject nothing. An agent cannot set `PLAN_ID` for the hook process, but it can
move finished plans out of `.planning/` until one remains, which restores
automatic selection. Archiving tidies the workspace; it does not free disk
space. Archive only plans the user approved.

```sh
sh "<skill-dir>/scripts/set-active-plan.sh" --archive <id>
sh "<skill-dir>/scripts/set-active-plan.sh" --archive <id> --yes
sh "<skill-dir>/scripts/set-active-plan.sh" --list --archived
sh "<skill-dir>/scripts/set-active-plan.sh" --restore <id> --yes
```

```powershell
& "<skill-dir>/scripts/set-active-plan.ps1" -Archive <id>
& "<skill-dir>/scripts/set-active-plan.ps1" -Archive <id> -Yes
& "<skill-dir>/scripts/set-active-plan.ps1" -List -Archived
& "<skill-dir>/scripts/set-active-plan.ps1" -Restore <id> -Yes
```

Both commands act on the current directory's `.planning/` only and ignore
`PWF_PLAN_ROOT`. Without `--yes` (`-Yes`), archive and restore print a preview
and change nothing. The archive preview shows phase counts, the source and
destination paths, a note when not all phases are complete, and whether the
shared default (`.active_plan`) would be cleared. With `--yes`, archive moves
`.planning/<id>/` to `.planning/.archive/<id>/` in one rename and creates
`.planning/.archive/` when needed; if the rename then fails, a
`.planning/.archive/` this call created is removed again while it is still
empty. Attestation, mode and other files inside the plan directory move with
it. If `.planning/.active_plan` names the archived plan's directory (read as
the resolver reads it: BOM and whitespace removed), the pointer file is
removed and the output says so. Restore moves the directory back and never
touches `.active_plan`. Plain `--list` points at archiving in its footer and,
when archived plans exist, gives their number.

An ID must match the directory name exactly, including case: on a
case-insensitive filesystem `ALPHA` does not archive `alpha`, and on Windows
`alpha.` does not archive `alpha`. The `PLAN_ID` guard compares directories,
so a pin spelled `ALPHA` still protects `alpha` where the resolver would
select it.

Both commands exit 1 with an `Error:` line on stderr and change nothing when:

- the ID does not match `^[A-Za-z0-9_][A-Za-z0-9._-]*$`, or the arguments
  do not form one of the commands above;
- `.planning/`, `.planning/.archive/` or the source directory is a link, a
  junction or outside the project;
- the source directory is missing, is not listed under exactly that name, or
  has no regular `task_plan.md`;
- the destination exists in any form, including a dangling link;
- `PLAN_ID` in the current environment names the directory being archived;
- (shell) the source and destination are on different filesystems, or this
  cannot be determined.

Nothing is deleted, copied across volumes or overwritten. Nothing is archived
automatically: hooks, initialization and completion checks never archive, and
no plan is chosen by age or completion. Only named plans can be archived; the
legacy root `task_plan.md` is out of scope.

The helper cannot prove that no session still uses a plan. It cannot see
Hermes profile bindings or a `PLAN_ID` set in another session's process. A
session pinned to an archived ID resolves to nothing, never to another plan;
restore the plan or change the pin.
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