docs(readme): update AGENTS.md merge strategy and pb-init behavior

Author: Akagi201

README.md

@@ -24,7 +24,7 @@ pb-spec follows a **harness-first** philosophy: reliability comes from process d
 | [Reflexion](https://arxiv.org/abs/2303.11366) | Learn from failure signals via iterative retries | Retry/skip/abort and DCR flow in `pb-build` |
 | [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) | Grounding, context hygiene, recovery, observability | State checks, minimal context handoff, task-local rollback guidance |
 | [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) | Prefer simple composable workflows over framework complexity | Small adapter-based CLI + explicit workflow prompts |
-| [Stop Using /init for AGENTS.md](https://addyosmani.com/blog/agents-md/) | Prefer minimal AGENTS.md (only undiscoverable facts) | `/pb-init` audits repo and generates minimal AGENTS.md with strict three-part filter (not inferrable, operationally decisive, not guessable) |
+| [Stop Using /init for AGENTS.md](https://addyosmani.com/blog/agents-md/) | Keep AGENTS.md focused and maintainable | `/pb-init` updates a managed snapshot block in `AGENTS.md` while preserving all user-authored constraints outside that block |
 
 ### Practical Principles in pb-spec
 
@@ -61,7 +61,7 @@ pb-spec init --ai claude       # or: copilot, opencode, gemini, codex, all
 pb-spec init --ai all -g       # install globally to each agent's home/config dir
 
 # 2. Open the project in your AI coding assistant and use the installed commands/prompts:
-#    /pb-init                          → Audit repo, produce minimal AGENTS.md (only undiscoverable facts)
+#    /pb-init                          → Audit repo, append/update a managed AGENTS.md snapshot block (non-destructive)
 #    /pb-plan Add WebSocket auth       → Generate specs/YYYY-MM-DD-01-add-websocket-auth/
 #    /pb-refine add-websocket-auth     → (Optional) Refine design based on feedback
 #    /pb-build add-websocket-auth      → Implement tasks via TDD subagents
@@ -111,9 +111,20 @@ four agent skills that chain together:
 /pb-init → /pb-plan → [/pb-refine] → /pb-build
 ```
 
-### 1. `/pb-init` — AGENTS.md Audit & Minimization
+### 1. `/pb-init` — AGENTS.md Snapshot & Safe Merge
 
-Audits your project and produces an **extremely minimal** `AGENTS.md` at the project root. Instead of dumping project overview info that agents can discover themselves, it applies a strict three-part filter: each entry must be (1) not inferrable from code, (2) operationally decisive, and (3) not guessable from industry conventions. Every entry in AGENTS.md represents a codebase smell — the goal is to fix root causes and drive AGENTS.md toward zero entries over time. **Preserves user-added context** across re-runs.
+Audits your project and writes a `pb-init` snapshot into `AGENTS.md` using managed markers:
+
+- `<!-- BEGIN PB-INIT MANAGED BLOCK -->`
+- `<!-- END PB-INIT MANAGED BLOCK -->`
+
+Merge behavior is non-destructive:
+
+- If markers exist, only that managed block is replaced.
+- If markers do not exist, the managed block is appended.
+- All existing content outside the managed block is preserved verbatim.
+
+This design avoids relying on any fixed `AGENTS.md` section layout and protects user-maintained constraints across re-runs.
 
 ### 2. `/pb-plan <requirement>` — Design & Task Planning
 
@@ -125,21 +136,21 @@ specs/<YYYY-MM-DD-NO-feature-name>/
 └── tasks.md     # Ordered implementation tasks (logical units of work)
 ```
 
-The spec directory follows the naming format `YYYY-MM-DD-NO-feature-name` (e.g., `2026-02-15-01-add-websocket-auth`). The feature-name part must be unique across all specs.
+The spec directory follows the naming format `YYYY-MM-DD-NO-feature-name` (e.g., `2026-02-15-01-add-websocket-auth`). The feature-name part must be unique across all specs. During planning, `AGENTS.md` is treated as read-only policy context (free-form, no fixed layout assumptions).
 
 ### 3. `/pb-refine <feature-name>` — Design Iteration (Optional)
 
-Reads user feedback or Design Change Requests (from failed builds) and intelligently updates `design.md` and `tasks.md`. It maintains a revision history and cascades design changes to the task list without overwriting completed work.
+Reads user feedback or Design Change Requests (from failed builds) and intelligently updates `design.md` and `tasks.md`. It maintains a revision history and cascades design changes to the task list without overwriting completed work. `AGENTS.md` remains read-only in this phase.
 
 ### 4. `/pb-build <feature-name>` — Subagent-Driven Implementation
 
-Reads `specs/<YYYY-MM-DD-NO-feature-name>/tasks.md` and implements each task sequentially. Every task is executed by a fresh subagent following strict TDD (Red → Green → Refactor). Supports **Design Change Requests** if the planned design proves infeasible during implementation. Only the `<feature-name>` part is needed when invoking — the agent resolves the full directory automatically.
+Reads `specs/<YYYY-MM-DD-NO-feature-name>/tasks.md` and implements each task sequentially. Every task is executed by a fresh subagent following strict TDD (Red → Green → Refactor). Supports **Design Change Requests** if the planned design proves infeasible during implementation. Only the `<feature-name>` part is needed when invoking — the agent resolves the full directory automatically. `AGENTS.md` is read-only unless the user explicitly requests an `AGENTS.md` change.
 
 ## Skills Overview
 
 | Skill | Trigger | Output | Description |
 |---|---|---|---|
-| `pb-init` | `/pb-init` | `AGENTS.md` | Audit repo for undiscoverable gotchas, produce minimal agent context |
+| `pb-init` | `/pb-init` | `AGENTS.md` | Audit repo and safely update/append a managed snapshot block without rewriting user-authored constraints |
 | `pb-plan` | `/pb-plan <requirement>` | `specs/<YYYY-MM-DD-NO-feature-name>/design.md` + `tasks.md` | Design proposal + ordered task breakdown |
 | `pb-refine` | `/pb-refine <feature>` | Revised spec files | Apply feedback or Design Change Requests |
 | `pb-build` | `/pb-build <feature-name>` | Code + tests | TDD implementation via subagents |
@@ -155,16 +166,16 @@ pb-spec's prompt design is inspired by Anthropic's research on [Effective Harnes
 | **State Grounding** | Subagents must verify workspace state (`ls`, `find`, `read_file`) before writing any code — preventing path hallucination |
 | **Error Quoting** | Subagents must quote specific error messages before attempting fixes — preventing blind debugging |
 | **Context Hygiene** | Orchestrator passes only minimal, relevant context to each subagent — preventing context window pollution |
-| **Recovery Loop** | Failed tasks trigger `git checkout .` (workspace revert) before retry — ensuring each attempt starts from a known-good state |
+| **Recovery Loop** | Failed tasks use pre-task snapshots + file-scoped recovery (`git restore` + task-local cleanup), and avoid workspace-wide restore in dirty trees |
 | **Verification Harness** | Design docs define explicit verification commands at planning time — subagents execute, not invent, verification |
-| **Agent Rules** | `AGENTS.md` contains only undiscoverable gotchas and hard constraints — not project overview info that agents can infer from code |
+| **Agent Rules** | `AGENTS.md` is treated as free-form policy context: `pb-init` manages only its marker block; `pb-plan`/`pb-refine`/`pb-build` read it without rewriting |
 
 ### Where Each Principle Lives
 
 - **Worker (Implementer):** `implementer_prompt.md` enforces grounding-first workflow and error quoting
 - **Architect (Planner):** `design_template.md` includes Critical Path Verification table
-- **Orchestrator (Builder):** `pb-build` SKILL enforces context hygiene and workspace revert on failure
-- **Foundation (Init):** `AGENTS.md` captures only non-obvious gotchas, hard constraints, and traps that agents cannot infer from code — not a full project overview
+- **Orchestrator (Builder):** `pb-build` SKILL enforces context hygiene and task-local recovery with safe rollback rules
+- **Foundation (Init):** `pb-init` updates only the managed marker block in `AGENTS.md`, preserving all external user-authored constraints
 
 ## Development
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pb-spec"
-version = "0.4.5"
+version = "0.5.0"
 description = "Plan-Build Spec (pb-spec): A CLI tool for managing AI coding assistant skills"
 readme = "README.md"
 license = "Apache-2.0"
@@ -41,8 +41,8 @@ testpaths = ["tests"]
 [dependency-groups]
 dev = [
     "pytest>=9.0.2",
-    "ruff>=0.15.1",
-    "ty>=0.0.17",
+    "ruff>=0.15.4",
+    "ty>=0.0.19",
 ]
 
 [tool.ruff]

src/pb_spec/templates/prompts/pb-build.prompt.md

@@ -61,12 +61,12 @@ If all tasks are checked (`- [x]`), report:
 For each unfinished task, in order:
 
 1. **Extract** the full task block (Context, Steps, Verification).
-2. **Gather context** — read `design.md` and `AGENTS.md` (if it exists).
+2. **Gather context** — read `design.md` and `AGENTS.md` (if it exists). Treat `AGENTS.md` as read-only policy context.
    - Record a pre-task workspace snapshot (`git status --porcelain` + tracked/untracked file lists) for safe rollback.
 3. **Spawn a fresh subagent** with the Implementer Prompt (below), filled in with the task content and project context.
    **Context Hygiene:** Do NOT pass the entire chat history. Pass ONLY:
    - The specific Task Description from `tasks.md`.
-   - The `AGENTS.md` (non-obvious gotchas and hard constraints — intentionally minimal).
+   - The `AGENTS.md` (project constraints and hard rules; do not assume any fixed template layout).
    - The `design.md` (Feature Spec).
    - **Summary of previous tasks** — a one-line-per-task summary (e.g., "Task 1.1 created `models.py` with `User` class."). Do NOT pass raw logs or full outputs.
 4. **Subagent executes** the TDD cycle (see Implementer Prompt section).
@@ -180,6 +180,7 @@ Update `tasks.md` in-place after each task using **precise edits** (target the s
 - Let a subagent implement more than its assigned task.
 - Carry in-memory state between subagents.
 - Modify `design.md` (file a Design Change Request instead).
+- Modify, delete, or reformat `AGENTS.md` unless the user explicitly requests an `AGENTS.md` change.
 - Rewrite the entire `tasks.md` file — use targeted edits only.
 - Mark a task as done without satisfying its Verification criteria.
 - Claim tests passed without running them.
@@ -230,7 +231,7 @@ You are implementing **Task {{TASK_NUMBER}}: {{TASK_NAME}}**.
 
 {{PROJECT_CONTEXT}}
 
-> From `AGENTS.md` (non-obvious gotchas and constraints) and `design.md` (feature design decisions).
+> From `AGENTS.md` (project constraints and rules) and `design.md` (feature design decisions).
 
 ### Your Job
 
@@ -307,6 +308,7 @@ Fix any "no" answers before submitting.
 - Follow YAGNI — no speculative features.
 - Use existing patterns — match project style.
 - Do not modify `design.md` or `tasks.md`.
+- Do not modify, delete, or reformat `AGENTS.md` unless the user explicitly requests an `AGENTS.md` change.
 - Do not modify unrelated code.
 - Tests are mandatory — never submit without them.
 - **No Blind Edits:** Always read a file before editing it.

src/pb_spec/templates/prompts/pb-init.prompt.md

@@ -80,48 +80,55 @@ Output format per spec:
 - `specs/<YYYY-MM-DD-NO-feature-name>/` — <status emoji> <status text> | Design: <design status> | Last modified: YYYY-MM-DD
 ```
 
-## Step 5: Write AGENTS.md (Incremental Merge)
+## Step 5: Write AGENTS.md (Managed Block, Non-Destructive)
 
-Write the following content to `AGENTS.md` at the project root.
+Write or update `AGENTS.md` at the project root using a **marker-based managed block**. Do NOT parse or rewrite user sections based on heading names.
 
-**Preserving User Content — Merge Strategy:** Before writing, check if `AGENTS.md` already exists. If it does:
+**Managed block markers (fixed):**
 
-1. Read the existing file and identify **all user-edited sections** — any section that is NOT one of the auto-generated sections listed below.
-2. **Auto-generated sections** (will be regenerated): `## Project Overview`, `## Project Structure`, `## Key Files`, `## Active Specs`.
-3. **Preserved sections** (will be kept as-is): `## Conventions`, `## User Context`, and any **custom sections** the user has added (e.g., `## Database Schema`, `## API Notes`, `## Team Conventions`).
-4. **Merge procedure:**
-   a. Regenerate auto-generated sections with fresh data.
-   b. For `## Conventions`: if it exists in the old file, keep the user's version. If not, generate the default.
-   c. Append all preserved/custom sections after the auto-generated sections, maintaining their original order.
-   d. Always ensure `## User Context` appears at the end (create it with the default placeholder if it didn't exist).
+- `<!-- BEGIN PB-INIT MANAGED BLOCK -->`
+- `<!-- END PB-INIT MANAGED BLOCK -->`
 
-This ensures ALL user-added content survives re-initialization — not just `## User Context`.
+**Merge procedure (strict):**
+
+1. Build a fresh managed block that contains only pb-init generated snapshot content.
+2. If `AGENTS.md` does not exist: create it with the managed block.
+3. If `AGENTS.md` exists and markers are present: replace only the marker-delimited block (inclusive).
+4. If `AGENTS.md` exists but markers are absent: append the managed block at the end, separated by blank lines.
+5. Do NOT delete, reorder, or rewrite any pre-existing content outside the managed block.
+6. Never assume a specific `AGENTS.md` format, section name, or template structure.
+
+This strategy is format-agnostic and prevents accidental loss of user-maintained constraints.
 
 ```markdown
 # AGENTS.md
 
+<!-- Existing user-authored constraints can live anywhere in this file. -->
+<!-- BEGIN PB-INIT MANAGED BLOCK -->
+## pb-init Snapshot
+
 > Auto-generated by pb-init. Last updated: YYYY-MM-DD
 
-## Project Overview
+### Project Overview
 
 - **Language**: <detected language>
 - **Framework**: <detected framework, or "None detected">
 - **Build Tool**: <detected build tool>
 - **Test Command**: `<detected test command>`
 
-## Project Structure
+### Project Structure
 ```
 
 <directory tree from adaptive traversal>
 ```
 
-## Key Files
+### Key Files
 
 - Entry point: <path>
 - Config: <path>
 - Tests: <path>
 
-## Conventions
+### Suggested Conventions (Optional Defaults)
 
 - Commit style: conventional commits
 - Branch strategy: feature branches
@@ -132,13 +139,10 @@ This ensures ALL user-added content survives re-initialization — not just `##
   4. **Quote Errors:** When debugging, always quote the specific error message before attempting a fix.
   5. **Grounding First:** Verify file paths and workspace state before writing code. Use `ls` / `find` / file search.
 
-## Active Specs
+### Active Specs
 
 <list of specs/<YYYY-MM-DD-NO-feature-name> directories with dynamic status, or "No active specs found.">
-
-## User Context
-
-<!-- Add your project-specific notes below. This section is preserved across pb-init runs. -->
+<!-- END PB-INIT MANAGED BLOCK -->
 
 ```text
 
@@ -150,7 +154,7 @@ Replace `YYYY-MM-DD` with today's date.
 
 - **Read-only analysis.** Do NOT modify any project source code, config files, or tests.
 - **Only write `AGENTS.md`.** That is the sole file you create or modify.
-- **Incremental merge.** Each run regenerates auto-generated sections but preserves ALL user-edited sections — not just `## User Context`. Custom sections added by the user are kept intact.
+- **Non-destructive merge.** Never delete, normalize, or reorder existing `AGENTS.md` content outside the pb-init managed block.
 - **No interactive questions.** Analyze and produce output in a single pass.
 
 ## Edge Cases
@@ -160,3 +164,4 @@ Replace `YYYY-MM-DD` with today's date.
 - **Monorepo:** If multiple `package.json` / `Cargo.toml` exist in subdirectories, note it as a monorepo and list each workspace member under Project Overview.
 - **Empty project:** Generate a minimal `AGENTS.md` with "Empty project — no source files detected" in the overview.
 - **`specs/` does not exist:** Write "No active specs found." in the Active Specs section.
+- **Legacy `AGENTS.md` without markers:** Do not attempt structural parsing. Append the managed block once; preserve all existing text verbatim.

src/pb_spec/templates/prompts/pb-plan.prompt.md

@@ -51,7 +51,7 @@ Count the words in the requirement description (excluding the `/pb-plan` trigger
 
 Gather context to inform the design. **Always perform live codebase analysis** — do not rely on any static file.
 
-1. **Read `AGENTS.md`** (if it exists) — check for non-obvious gotchas, hard constraints, and traps that you cannot infer from code. AGENTS.md intentionally omits discoverable info (language, structure, test commands) — you must find those yourself.
+1. **Read `AGENTS.md`** (if it exists) — capture explicit project constraints, team rules, and gotchas. Do not assume any fixed section layout; treat it as free-form user-authored policy text.
 2. **Search the live codebase directly** — this is **mandatory** regardless of whether `AGENTS.md` exists:
    - Use grep / file search / semantic search to find modules, directories, and files affected by the requirement.
    - Search for keywords from the requirement across the codebase.
@@ -200,7 +200,7 @@ Please review the design and tasks. When ready, run /pb-build <feature-name> to
 1. **One-shot output.** Complete design + tasks in a single pass. No mid-way confirmation.
 2. **Optimal solution first.** Output the best design. Developer requests changes after review if needed.
 3. **Right-sized output (YAGNI).** Match output detail to requirement complexity. Simple changes get compact specs; complex features get full specs.
-4. **Live codebase analysis.** Always search the actual codebase — `AGENTS.md` contains only non-obvious gotchas, not project overview info.
+4. **Live codebase analysis.** Always search the actual codebase. Use `AGENTS.md` as complementary policy context, not a replacement for code inspection.
 5. **Task granularity: Logical Unit of Work.** Each task is a self-contained, meaningful change. Do not split based on arbitrary time estimates.
 6. **Verification per task.** Every task defines how to prove it is done.
 7. **Dependency order.** Phases and tasks flow foundational → dependent.
@@ -218,6 +218,7 @@ Please review the design and tasks. When ready, run /pb-build <feature-name> to
 - **No code implementation.** Design docs and task lists only.
 - **Scope-appropriate templates.** In lightweight mode, only fill the compact template. In full mode, fill the complete template. Every included section must have substantive content.
 - **Write only to `specs/<spec-dir>/`.** Do not modify project source code.
+- **`AGENTS.md` is read-only in this phase.** Do not modify, delete, or reformat it unless the user explicitly asks for an `AGENTS.md` update.
 - **No invented references.** Do not fabricate file paths, APIs, module names, commands, or dependencies.
 - **No unresolved placeholders.** Final `design.md` and `tasks.md` must not contain template example markers like `[Goal A]` or `[Task Name]`.
 

src/pb_spec/templates/prompts/pb-refine.prompt.md

@@ -25,7 +25,7 @@ Run this when the user invokes `/pb-refine <feature-name>` with feedback or chan
 
 1. `specs/<spec-dir>/design.md` — the current design.
 2. `specs/<spec-dir>/tasks.md` — the current task breakdown.
-3. `AGENTS.md` (if it exists) — non-obvious constraints and gotchas.
+3. `AGENTS.md` (if it exists) — read-only source of constraints and gotchas.
 
 ## Step 2: Parse User Feedback
 
@@ -123,6 +123,7 @@ Next steps:
 - **Do not modify project source code.** Refinement is planning only.
 - **Do not re-run the entire planning process.** This is an incremental update, not a fresh plan.
 - **Preserve formatting and structure** of both files.
+- **`AGENTS.md` is read-only in this phase.** Do not modify, delete, or reformat it unless the user explicitly asks for an `AGENTS.md` update.
 - **No interactive multi-turn probing.** Apply the feedback given. If the feedback is ambiguous, state your interpretation in the Revision History and proceed.
 
 ---