docs(init): clarify AGENTS.md minimization and context hygiene

Author: Akagi201

README.md

@@ -24,6 +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) |  |
 
 ### Practical Principles in pb-spec
 
@@ -60,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                          → Generate AGENTS.md project context
+#    /pb-init                          → Audit repo, produce minimal AGENTS.md (only undiscoverable facts)
 #    /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
@@ -110,9 +111,9 @@ four agent skills that chain together:
 /pb-init → /pb-plan → [/pb-refine] → /pb-build
 ```
 
-### 1. `/pb-init` — Project Initialization
+### 1. `/pb-init` — AGENTS.md Audit & Minimization
 
-Analyzes your project and generates an `AGENTS.md` file at the project root. This file captures the tech stack, directory structure, conventions, and testing patterns. **Preserves user-added context** so manual notes aren't lost on re-runs.
+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.
 
 ### 2. `/pb-plan <requirement>` — Design & Task Planning
 
@@ -138,7 +139,7 @@ Reads `specs/<YYYY-MM-DD-NO-feature-name>/tasks.md` and implements each task seq
 
 | Skill | Trigger | Output | Description |
 |---|---|---|---|
-| `pb-init` | `/pb-init` | `AGENTS.md` | Detect stack, scan structure, generate project context |
+| `pb-init` | `/pb-init` | `AGENTS.md` | Audit repo for undiscoverable gotchas, produce minimal agent context |
 | `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 |
@@ -156,14 +157,14 @@ pb-spec's prompt design is inspired by Anthropic's research on [Effective Harnes
 | **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 |
 | **Verification Harness** | Design docs define explicit verification commands at planning time — subagents execute, not invent, verification |
-| **Agent Rules** | `AGENTS.md` embeds project-specific "laws of physics" that all subagents inherit as system-level constraints |
+| **Agent Rules** | `AGENTS.md` contains only undiscoverable gotchas and hard constraints — not project overview info that agents can infer from code |
 
 ### 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` template includes Agent Harness Rules as global conventions
+- **Foundation (Init):** `AGENTS.md` captures only non-obvious gotchas, hard constraints, and traps that agents cannot infer from code — not a full project overview
 
 ## Development
 

docs/design.md

@@ -101,7 +101,7 @@ Behavior guarantees:
 
 ### 6.1 pb-init
 
-Generates/merges `AGENTS.md` from live repository state. It preserves user-authored sections while refreshing generated sections.
+Audits the repository and produces a **minimal** `AGENTS.md` containing only information that agents cannot discover from the codebase itself. 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. The ideal AGENTS.md is empty — every entry represents a codebase smell that should eventually be fixed at the root cause. Re-runs audit existing entries and flag any that are now discoverable.
 
 ### 6.2 pb-plan
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pb-spec"
-version = "0.4.4"
+version = "0.4.5"
 description = "Plan-Build Spec (pb-spec): A CLI tool for managing AI coding assistant skills"
 readme = "README.md"
 license = "Apache-2.0"

src/pb_spec/platforms/base.py

@@ -6,8 +6,8 @@
 # Skill metadata: name -> description
 SKILL_METADATA: dict[str, str] = {
     "pb-init": (
-        "Use when onboarding a repo or after major structural changes to regenerate AGENTS.md "
-        "project context."
+        "Use to audit the repo and produce a minimal AGENTS.md containing only "
+        "undiscoverable gotchas, hard constraints, and non-obvious conventions."
     ),
     "pb-plan": (
         "Use when converting a requirement into a design proposal and executable tasks before coding."

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`.
+2. **Gather context** — read `design.md` and `AGENTS.md` (if it exists).
    - 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` (Project Rules & Conventions).
+   - The `AGENTS.md` (non-obvious gotchas and hard constraints — intentionally minimal).
    - 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).
@@ -141,7 +141,7 @@ Summary must be factual and command-backed: do not claim "passed" or "completed"
 ## Subagent Rules
 
 1. **One subagent per task.** Never combine tasks.
-2. **Fresh context per subagent.** Only: task description, project context (AGENTS.md + design.md), summary of completed tasks, files on disk.
+2. **Fresh context per subagent.** Only: task description, non-obvious constraints (AGENTS.md) + design (design.md), summary of completed tasks, files on disk.
 3. **Sequential execution.** Strict `tasks.md` order. No parallelism.
 4. **Independence.** Cross-task state lives in files, not memory.
 5. **Grounding first.** Every subagent verifies workspace state before writing code.
@@ -230,7 +230,7 @@ You are implementing **Task {{TASK_NUMBER}}: {{TASK_NAME}}**.
 
 {{PROJECT_CONTEXT}}
 
-> From `AGENTS.md` and `design.md` — tech stack, conventions, design decisions.
+> From `AGENTS.md` (non-obvious gotchas and constraints) and `design.md` (feature design decisions).
 
 ### Your Job
 
@@ -268,7 +268,7 @@ Before writing any code, verify the current workspace state:
 
 - [ ] Completeness — everything the task requires is implemented
 - [ ] Nothing extra — no work beyond this task
-- [ ] Conventions — code follows project style from `AGENTS.md`
+- [ ] Conventions — code follows project style (discover from codebase; check `AGENTS.md` for non-obvious constraints)
 - [ ] Test coverage — tests meaningfully verify requirements
 - [ ] No regressions — all pre-existing tests pass
 - [ ] YAGNI — no over-engineering

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

@@ -49,9 +49,9 @@ Count the words in the requirement description (excluding the `/pb-plan` trigger
 
 ## Step 2: Collect Project Context
 
-Gather context to inform the design. **Do not rely solely on `AGENTS.md`** — always perform live codebase analysis.
+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) — use as a starting reference. **Treat as supplementary, not authoritative** — verify against actual project state.
+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.
 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.
@@ -66,7 +66,7 @@ Gather context to inform the design. **Do not rely solely on `AGENTS.md`** — a
 
    **This audit is mandatory.** List reusable components in `design.md` Section 3.3 and reference them in `tasks.md` task context.
 
-If `AGENTS.md` does not exist, search the codebase directly for project context. Recommend running `/pb-init` first in your summary.
+If `AGENTS.md` does not exist, that's fine — scan the project root directly (config files, directory structure) to infer project context. You can recommend running `/pb-init` to surface any hidden gotchas, but its absence should not block planning.
 
 **Evidence precedence (highest to lowest):**
 
@@ -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 — never rely solely on `AGENTS.md` which may be stale.
+4. **Live codebase analysis.** Always search the actual codebase — `AGENTS.md` contains only non-obvious gotchas, not project overview info.
 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.
@@ -228,7 +228,7 @@ Please review the design and tasks. When ready, run /pb-build <feature-name> to
 - **Ambiguous requirements:** Make reasonable assumptions. State them in the design's Assumptions section.
 - **Large scope (>40h of tasks):** Split into phases. First phase = viable MVP. Note in summary.
 - **Same feature-name exists:** The uniqueness check in Step 3 prevents creating a spec with a feature-name that already exists in `specs/`. Stop and report the conflict. The developer should choose a different name or use `/pb-refine` to update the existing spec.
-- **No `AGENTS.md`:** Proceed anyway — search codebase directly. Recommend running `/pb-init` first.
+- **No `AGENTS.md`:** Proceed anyway — search codebase directly. Recommend `/pb-init` to surface hidden gotchas.
 - **Bug fix, not feature:** Use same process. Design focuses on root cause + fix approach.
 - **External systems/APIs:** Document assumptions about external interfaces in design.
 - **Borderline word count (~50 words):** Use lightweight mode. Developer can run `/pb-refine` to expand.

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) — project context.
+3. `AGENTS.md` (if it exists) — non-obvious constraints and gotchas.
 
 ## Step 2: Parse User Feedback
 

src/pb_spec/templates/skills/pb-build/SKILL.md

@@ -71,7 +71,7 @@ Extract the full task block from `tasks.md` — including Context, Steps, and Ve
 #### 3b. Gather Project Context
 
 - Read `specs/<spec-dir>/design.md` for design context.
-- Read `AGENTS.md` (if it exists) for project conventions.
+- Read `AGENTS.md` (if it exists) for non-obvious gotchas and hard constraints.
 - Identify files most relevant to this task.
 - Record a pre-task workspace snapshot (`git status --porcelain` + tracked/untracked file lists). This baseline is used for safe recovery if the task fails.
 
@@ -80,14 +80,14 @@ Extract the full task block from `tasks.md` — including Context, Steps, and Ve
 Create a **fresh subagent** for this task. Pass it the implementer prompt template from `references/implementer_prompt.md`, filled with:
 
 - The full task description from `tasks.md`.
-- Project context from `AGENTS.md` and `design.md`.
+- Non-obvious constraints from `AGENTS.md` and design context from `design.md`.
 - The task number and name.
 
 **Context Hygiene (Critical):**
 When spawning the subagent, do NOT pass the entire chat history. Pass ONLY:
 
 1. The specific Task Description from `tasks.md`.
-2. The `AGENTS.md` (Project Rules & Conventions).
+2. The `AGENTS.md` (non-obvious gotchas and hard constraints — intentionally minimal).
 3. The `design.md` (Feature Spec).
 4. **Summary of previous tasks** — a one-line-per-task summary of what was done (e.g., "Task 1.1 created `models.py` with `User` and `Session` classes which you should now use."). Do NOT pass raw logs or full outputs from previous subagents.
 

src/pb_spec/templates/skills/pb-build/references/implementer_prompt.md

@@ -16,7 +16,7 @@ You are implementing **Task {{TASK_NUMBER}}: {{TASK_NAME}}**.
 
 {{PROJECT_CONTEXT}}
 
-> The above is assembled from `AGENTS.md` (project conventions) and `design.md` (feature design). Use it to understand the tech stack, coding style, project structure, and design decisions.
+> The above is assembled from `AGENTS.md` (non-obvious gotchas and hard constraints) and `design.md` (feature design). AGENTS.md is intentionally minimal — discover tech stack, structure, and conventions directly from the codebase.
 
 ---
 
@@ -104,7 +104,7 @@ Before submitting, answer each question honestly:
 
 - [ ] **Completeness:** Did I implement everything the task requires?
 - [ ] **Nothing extra:** Did I avoid implementing things not in this task?
-- [ ] **Conventions:** Does the code follow project conventions from `AGENTS.md`?
+- [ ] **Conventions:** Does the code follow project conventions (discovered from codebase; `AGENTS.md` for non-obvious constraints)?
 - [ ] **Test coverage:** Do the tests meaningfully verify the task's requirements?
 - [ ] **No regressions:** Do all pre-existing tests still pass?
 - [ ] **YAGNI:** Is there any over-engineering I should remove?

src/pb_spec/templates/skills/pb-plan/SKILL.md

@@ -53,9 +53,9 @@ Count the words in the requirement description (excluding the `/pb-plan` trigger
 
 ### Step 2: Collect Project Context
 
-Gather context to inform the design. **Do not rely solely on `AGENTS.md`** — always perform live codebase analysis.
+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 at project root) — use as a starting reference for language, framework, build tool, project structure, and conventions. **Treat as supplementary, not authoritative** — verify against actual project state.
+1. **Read `AGENTS.md`** (if it exists at project root) — 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.
 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 (function names, class names, module names, config keys).
@@ -70,7 +70,7 @@ Gather context to inform the design. **Do not rely solely on `AGENTS.md`** — a
 
    **This audit is mandatory.** List reusable components in `design.md` Section 3.3 and reference them in `tasks.md` task context.
 
-If `AGENTS.md` does not exist, scan the project root directly (config files, directory structure) to infer project context. Recommend running `/pb-init` first in your summary.
+If `AGENTS.md` does not exist, that's fine — scan the project root directly (config files, directory structure) to infer project context. You can recommend running `/pb-init` to surface any hidden gotchas, but its absence should not block planning.
 
 **Evidence precedence (highest to lowest):**