From bdc1e124d1a55d3dd4721f2a4c9b4040732fb147 Mon Sep 17 00:00:00 2001
From: OthmanAdi <78882424+OthmanAdi@users.noreply.github.com>
Date: Sun, 9 Aug 2026 09:40:05 +0200
Subject: [PATCH] docs: make the top of the README readable on a phone
The before/after comparison was a raw
with width="50%" cells.
GitHub honors that legacy attribute directly, so the two columns lock to
a 50/50 split of a ~340px container instead of letting the table scroll
as one unit. The right cell holds a block, which does not reflow,
so the half that shows the actual injection payload got crushed into a
~160px strip with a nested scrollbar. Now two stacked sections, correct
at every width, with all wording and the plan-data block preserved.
The stats panel was a 48-column box-drawing block. 48 columns need about
375px of text width, more than any phone has in portrait, and every
value is right-flushed, so the labels rendered and the numbers were the
first thing pushed off screen. A first-time mobile visitor saw five
labels and no numbers. Now a two-column table, content-sized, widest
line 38 characters, and readable by screen readers.
Also documents PWF_PLAN_GUARD, records that the language variants are
real translations that now ship the full script surface, and corrects
the parity count from 18 to 19 (the npm package.json joined the set in
#213). Test suite figure updated to 417.
---
README.md | 38 ++++++++++++++++----------------------
1 file changed, 16 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
index b7d9823..dd84dc5 100644
--- a/README.md
+++ b/README.md
@@ -41,11 +41,7 @@ Persistent file-based planning for AI coding agents and long-running agent tasks
Every coding agent loses its working memory when the context window resets. The plan does not have to die with it.
-
-
-|
-
-**Without planning files**
+### Without planning files
> **you:** continue
>
@@ -53,10 +49,9 @@ Every coding agent loses its working memory when the context window resets. The
The agent re-reads the repo, asks you to restate the goal, and rediscovers work it already finished.
- |
-
+---
-**With planning-with-files**
+### With planning-with-files
```text
===BEGIN PLAN DATA===
@@ -73,21 +68,15 @@ The agent re-reads the repo, asks you to restate the goal, and rediscovers work
> **agent:** Resuming Phase 3: adding the expiry edge-case tests.
- |
-
-
-
The transcript is illustrative; the `===BEGIN PLAN DATA===` block is the skill's real injection format, written into context by the `UserPromptSubmit` hook from `task_plan.md` on disk. In the project's internal recovery benchmark, a fresh session with the files on disk resumed in 5.0 turns on average against 13.3 for a raw agent (internal v1, author-run; method and limits in [docs/evals.md](docs/evals.md)).
-```
-┌──────────────────────────────────────────────┐
-│ PLAN FILES 3 │
-│ AGENTS COVERED 60+ │
-│ PASS RATE (with skill) 96.7% │
-│ TEST SUITE 411 green │
-│ SURVIVES /clear yes │
-└──────────────────────────────────────────────┘
-```
+| | |
+|---|---:|
+| Plan files | **3** |
+| Agents covered | **60+** |
+| Pass rate (with skill) | **96.7%** |
+| Test suite | **417 green** |
+| Survives `/clear` | **yes** |
## The Problem
@@ -225,6 +214,10 @@ npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g
```
+These are real translations, not an English body with a translated description: the SKILL.md prose, the templates, and the user-facing output of `check-complete`, `init-session` and `session-catchup` are all localized. The status tokens stay literal English (`**Status:** complete`) on purpose, because `check-complete.sh` matches them with `grep -F`, so translating them would disable the completion gate.
+
+Since v3.10.0 the variants also ship the full script surface: attestation, the Stop gate, the ledger, phase status and plan-doctor used to be canonical-only, which quietly made every non-English install a subset install. See [issue #130](https://github.com/OthmanAdi/planning-with-files/issues/130) for why they stay separate skills rather than collapsing into one.
+
@@ -420,6 +413,7 @@ The v3 line adds features aimed at long-running agentic runs. Each one is listed
| `PWF_PLAN_ROOT=` | v3.9.0 | Pins the thread to a project root by absolute path, which `PLAN_ID` cannot express. Use it when the agent's cwd is a shared parent such as `/workspace` while the work lives in `/workspace/project`. A pin that does not resolve stops injection instead of falling back. |
| `PWF_SESSION_ID=` | v2.36.0 | Identifies the session for plan attachment. Only consulted when `.planning/sessions/` exists, in which case a session sees plan context only if `.planning/sessions/.attached` exists. Delete that directory to turn session isolation off. |
| `PWF_INJECT=smart` | v3.8.0 | Replaces the fixed `head -50` injection window with the goal, next step, current phase, the full in-progress phase, and the last three decisions. |
+| `PWF_PLAN_GUARD=0` | v3.10.0 | Turns off the parallel-write guard, which is on by default. The guard compares checked items and completed phases against the previous hook fire and prints one advisory line when they go DOWN, meaning a second session overwrote work. A `plan-guard-off` token in `.mode` does the same. |
| `PWF_MODE` | v2.39.0 | Pi extension runtime mode: `auto`, `parity`, `cache-safe`, `notify`. Also settable in `.pi/settings.json` under `planningWithFiles.mode`. |
| `PWF_GATE_CAP` | v3.0.0 | Maximum consecutive Stop-gate blocks in gated mode. Default 20. |
@@ -480,7 +474,7 @@ planning-with-files/
└── README.md
```
-Every release bumps 18 parity-locked copies via `scripts/bump-version.py`; a test fails if any variant lags.
+Every release bumps 19 parity-locked copies via `scripts/bump-version.py`; a test fails if any variant lags.