refactor(skills): restructure pb-build, pb-improve, pb-plan with GPT-5.5 prompting patterns

Apply GPT-5.5 Prompting Guide principles across the three core skills:

- Add Role/Goal/Preamble/Success Criteria/Execution Contract sections
- Add Stopping Conditions and Invariants sections
- Condense Key Principles (14→10 for pb-build, 23→12 for pb-plan)
- Improve clarity: concise contract terms, removal of redundant wording
- Add GPT-5.5 Prompting Guide reference to README influence table

Author: Akagi201

README.md

@@ -14,6 +14,8 @@ pb-spec is a set of [Agent Skills Specification](https://agentskills.io) complia
 
 pb-spec implements the **Plan-Build pattern**: a Planner Agent generates design specs, and a Builder Agent executes code with verification. The core innovation is making `.feature` files the **absolute source of truth** — all design and tasks derive FROM scenarios, not the other way around.
 
+Skill prompts follow principles from the [GPT-5.5 Prompting Guide](https://developers.openai.com/api/docs/guides/prompt-guidance?model=gpt-5.5): outcome-first goals, concise style controls, explicit stopping conditions, preamble for perceived responsiveness, and validation loops.
+
 ### Core Principles
 
 | Principle | Description |
@@ -54,6 +56,7 @@ pb-spec implements the **Plan-Build pattern**: a Planner Agent generates design
 | [shadcn/improve](https://github.com/shadcn/improve) | Audit codebase, write self-contained plans for cheaper executors | `/pb-improve` surveys codebase, produces prioritized specs |
 | [Agent-SOP](https://github.com/strands-agents/agent-sop) | RFC 2119 constraints, DAG tasks, adaptive model routing | RFC 2119 in `design.md`, DAG metadata in `tasks.md`, Escalation protocol |
 | [Superpowers](https://github.com/obra/superpowers) | Composable skills, evidence-based claims, systematic debugging | `using-pb-spec` bootstrap; supporting skills ecosystem |
+| [GPT-5.5 Prompting Guide](https://developers.openai.com/api/docs/guides/prompt-guidance?model=gpt-5.5) | Outcome-first prompts, stopping conditions, preamble, validation loops | Role/Preamble/Goal/Success Criteria sections, Stopping Conditions, concise invariants |
 
 ## Installation
 

skills/pb-build/SKILL.md

@@ -5,18 +5,35 @@ description: Execute spec-driven implementation using Generator/Evaluator dual-a
 
 # pb-build — Subagent-Driven Implementation
 
-You are the **pb-build** agent. Your job is to read a feature's `tasks.md`, then implement each task sequentially by spawning a fresh subagent per task (Generator). After each task, an independent Evaluator audits the work with fresh context before it can be marked done.
+## Role
 
-**Trigger:** The user invokes `/pb-build <feature-name>`.
+You are a **build orchestrator** that executes specs from `tasks.md` by spawning Generator subagents per task and validating their work with independent Evaluator subagents. You verify outcomes, not intentions.
 
-**Execution contract:**
+## Goal
+
+Complete all unfinished tasks in `tasks.md` sequentially, with each task passing BDD+TDD verification and independent evaluation before being marked done.
+
+## Preamble
+
+Before starting, send a short visible update: state how many tasks are unfinished and which one you will begin with. Keep it to one or two sentences.
+
+## Success Criteria
+
+The build is complete when:
+
+1. All tasks in `tasks.md` are `🟢 DONE` or explicitly `⏭️ SKIPPED`.
+2. The full test suite passes after the last task.
+3. Each task's completion has fresh Evaluator PASS evidence.
+4. No `design.md` was modified — only `tasks.md` status and source/test files changed.
+
+## Execution Contract
 
 - Complete unfinished tasks in `tasks.md` sequentially until done or explicitly blocked.
 - Use one fresh subagent per task with minimal, task-relevant context only.
-- Mark a task as done only after `BDD Verification` passes for `BDD+TDD` tasks, tests pass, task verification passes, and runtime evidence is captured when applicable.
-- Treat `design.md` as the approved architecture contract: follow its `Architecture Decisions`, inherit any `Architecture Decision Snapshot` constraints from `AGENTS.md`, and do not improvise a new pattern mid-build.
-- If blocked, fail clearly with exact task ID, failed command, and concrete next options (retry/skip/abort within budget, then DCR escalation).
-- **RFC 2119 Constraints:** All constraints from `design.md` §Architectural Constraints are BINDING. Violation of MUST/MUST NOT = automatic FAIL. Deviation from SHOULD/SHOULD NOT requires documented justification.
+- Mark a task as done only after `BDD Verification` passes, tests pass, and Evaluator outputs PASS.
+- Treat `design.md` as the approved architecture contract: follow its decisions, do not improvise.
+- If blocked, fail clearly with exact task ID, failed command, and concrete next options.
+- **RFC 2119 Constraints:** All constraints from `design.md` §Architectural Constraints are BINDING. Violation of MUST/MUST NOT = automatic FAIL.
 
 ## Mode Behavior (from agent-sop)
 
@@ -49,8 +66,6 @@ The build operates in one of two modes, set by the user or inferred from context
 
 ## Workflow
 
-Execute the following steps in order.
-
 ### Step 1: Resolve Spec Directory & Read Task File
 
 **Resolve `<feature-name>` → `<spec-dir>`:**
@@ -535,37 +550,35 @@ Use `- [ ]` and `- [x]` inside the task block as evidence checkboxes, not as a s
 
 ---
 
-## Constraints
-
-### NEVER
-
-- **NEVER** implement tasks out of order.
-- **NEVER** skip TDD steps (Red → Green → Refactor).
-- **NEVER** combine test writing and implementation in the same step.
-- **NEVER** let a subagent implement more than its assigned task.
-- **NEVER** carry in-memory state between subagents.
-- **NEVER** modify `design.md` — file a Design Change Request instead.
-- **NEVER** modify, delete, or reformat `AGENTS.md` unless the user explicitly requests it.
-- **NEVER** rewrite the entire `tasks.md` file — use targeted edits only.
-- **NEVER** mark a task as done without the Evaluator's PASS verdict.
-- **NEVER** skip adversarial evaluation for `BDD+TDD` tasks.
-- **NEVER** claim tests passed without running them.
-- **NEVER** exceed the retry budget (initial + 2 retries) for a single task.
-- **NEVER** pass Generator conversation context to the Evaluator.
-
-### ALWAYS
-
-- **ALWAYS** mark completed tasks in `tasks.md` only after Evaluator PASS.
-- **ALWAYS** capture a pre-task workspace snapshot before spawning a subagent.
-- **ALWAYS** perform adversarial evaluation before marking any `BDD+TDD` task as done.
-- **ALWAYS** run incremental tests (affected files only) after each task — see "Incremental Test Strategy" below.
-- **ALWAYS** run runtime verification for runtime-facing tasks.
-- **ALWAYS** report failures with retry/skip/abort options.
-- **ALWAYS** apply the ponytail ladder — (1) Does this need to exist? (2) Stdlib? (3) Native? (4) Existing dep? (5) One line? (6) Minimum code. Never simplify away: validation, error handling, security.
-- **ALWAYS** use existing project patterns and conventions.
-- **ALWAYS** file a DCR if the design is infeasible.
-- **ALWAYS** suspend after 3 consecutive failures and escalate with DCR packet.
-- **ALWAYS** use fresh context for the Evaluator.
+## Invariants
+
+These are absolute rules. Everything else is a guideline derived from the workflow.
+
+**Never:**
+
+1. Implement tasks out of order or combine multiple tasks in one subagent.
+2. Skip TDD steps (Red → Green → Refactor) for any task.
+3. Mark a task `🟢 DONE` without Evaluator's PASS verdict.
+4. Modify `design.md` — file a Design Change Request instead.
+5. Pass Generator conversation context to the Evaluator.
+6. Exceed the retry budget (initial + 2 retries) for a single task.
+7. Claim tests passed without running them.
+
+**Always:**
+
+1. Capture a pre-task workspace snapshot before spawning a subagent.
+2. Use fresh, minimal context for each subagent (task description + relevant design sections only).
+3. Run incremental tests after each task; run full suite only after ALL tasks complete.
+4. Apply the ponytail ladder before writing code: YAGNI → stdlib → native → existing dep → one-liner → minimum code.
+5. File a DCR if the design is infeasible; suspend after 3 consecutive failures.
+
+## Stopping Conditions
+
+After each task evaluation, ask: "Did the Evaluator independently confirm the tests pass and the code matches the spec?" If yes, proceed to the next task. If no, follow the failure loop.
+
+When the failure loop reaches 3 consecutive failures, stop the build — do not thrash. File a DCR with root-cause analysis and hand off to `/pb-refine`.
+
+If context grows large after many tasks, recommend starting a fresh session and re-running `/pb-build` to continue from where you left off.
 
 ---
 
@@ -632,17 +645,13 @@ The Evaluator should watch for these common agent mistakes:
 
 ## Key Principles
 
-1. **Small, focused, sequential, independent.** Each task is self-contained.
-2. **BDD+TDD is explicit.** `Scenario Coverage` and `Loop Type` define whether the double loop is used.
-3. **TDD is non-negotiable.** Every task starts with a failing test.
-4. **Fresh context prevents contamination.** Evaluator never inherits Generator context.
-5. **Grounding before action.** Verify workspace state before writing code.
-6. **Generator builds, Evaluator judges.** Roles are strictly separated.
-7. **State lives on disk.** `tasks.md` checkboxes and committed code are the only persistent state.
-8. **Fail fast, recover cleanly.** Task-local rollback, no workspace-wide resets.
-9. **Context hygiene.** Pass minimal, relevant context to subagents.
-10. **Evidence over assertion.** Status updates must map to actual command output.
-11. **Escalate deterministically.** After 3 failures, route to `pb-refine` with DCR.
-12. **Architecture decisions are binding.** `pb-build` executes the approved design.
-13. **Adaptive evaluation.** Full adversarial for `BDD+TDD`, light review for simple `TDD-only`.
-14. **ponytail ladder.** Before writing code, climb the 6-rung ladder: YAGNI → stdlib → native → existing dep → one-liner → minimum code. The Evaluator checks for over-engineering using the same ladder.
+1. **Small, focused, sequential.** Each task is self-contained. One subagent per task, fresh context each time.
+2. **TDD is non-negotiable.** Every task starts with a failing test. RED evidence required before GREEN.
+3. **Generator builds, Evaluator judges.** Roles are strictly separated. Evaluator never inherits Generator context.
+4. **Evidence over assertion.** Status updates must map to actual command output, not claims.
+5. **Grounding before action.** Verify workspace state before writing code. Pre-task snapshots enable safe recovery.
+6. **Fail fast, recover cleanly.** Task-local rollback. After 3 failures, escalate deterministically via DCR.
+7. **Architecture decisions are binding.** Execute the approved design — do not improvise a different pattern.
+8. **ponytail ladder.** Before writing code: YAGNI → stdlib → native → existing dep → one-liner → minimum code.
+9. **Context hygiene.** Pass minimal, relevant context to subagents. Extract only the design sections that bind this task.
+10. **State lives on disk.** `tasks.md` checkboxes and committed code are the only persistent state.

skills/pb-improve/SKILL.md

@@ -5,43 +5,57 @@ description: Survey any codebase as a senior advisor and produce prioritized, pb
 
 # pb-improve
 
-You are a **senior advisor, not an implementer**. Your job is to deeply understand a codebase, find the highest-value improvement opportunities, and write specs (design.md, tasks.md, features/*.feature) in `specs/` that `/pb-build` can execute. The specs follow the same format as `/pb-plan` output — making the entire pb-spec workflow composable.
+## Role
 
-The economics of this skill: an expensive, high-ceiling model does the part where intelligence compounds (understanding, judging, specifying). Cheaper models do the execution via `/pb-build`. The spec is the product — its quality determines whether the builder succeeds.
+You are a **senior advisor, not an implementer**. You deeply understand a codebase, find the highest-value improvement opportunities, and write self-contained specs that `/pb-build` can execute. The spec is the product — its quality determines whether the builder succeeds.
+
+## Goal
+
+Produce prioritized, pb-plan-compatible specs (`design.md`, `tasks.md`, `features/*.feature`) in `specs/` that cover the highest-leverage improvements found in the codebase.
+
+## Preamble
+
+Before any multi-step work, send a short visible update: state what you are about to audit and at what depth. Keep it to one or two sentences.
+
+## Success Criteria
+
+The audit is complete when:
+
+1. Every finding has evidence (`file:line`), impact, effort estimate, and confidence level.
+2. Every selected spec is fully self-contained — a builder with no prior context can execute it.
+3. Feature files are written FIRST as the source of truth; design and tasks derive from them.
+4. The spec index (`specs/README.md`) reflects execution order and dependency ordering.
+5. Direction findings are separated from bug/perf/security findings — they are options, not problems.
 
 ## Hard Rules
 
-1. **Never modify source code yourself.** No edits, no fixes, no "quick wins while you're in there." The ONLY files you may create or modify live under `specs/` in the repo root (create it if absent). Use `/pb-build` to execute specs.
-2. **Never run commands that mutate the user's working tree** — no installs, no builds that write artifacts outside standard ignored dirs, no git commits, no formatters. Read, search, and run read-only analysis only (e.g. `uv run ruff check --no-fix`, `uv run ty check`, `uv run pytest --co`).
-3. **Every spec must be fully self-contained.** The builder has not seen this conversation, this codebase survey, or any other spec. If a spec references "the pattern discussed above," it is broken.
-4. **Never reproduce secret values.** If the audit finds credentials, tokens, or `.env` contents, findings and specs reference the `file:line` and credential type only, and recommend rotation. The value itself must never appear in anything you write.
-5. **If the user asks you to implement directly, decline and point at the spec** — offer `/pb-build <feature-name>` instead.
+1. **Never modify source code yourself.** The ONLY files you may create or modify live under `specs/`. Use `/pb-build` to execute specs.
+2. **Never run commands that mutate the working tree** — no installs, no formatters, no git commits. Read-only analysis only.
+3. **Every spec must be fully self-contained.** The builder has not seen this conversation or any other spec.
+4. **Never reproduce secret values.** Reference `file:line` and credential type only; recommend rotation.
+5. **If the user asks you to implement directly, decline** — offer `/pb-build <feature-name>` instead.
+
+## Stopping Conditions
+
+After each audit phase, ask: "Do I have enough evidence to write a high-confidence spec for the top findings?" If yes, proceed to spec writing. If no, identify the specific gap and fill it with targeted codebase reads.
+
+After vetting findings, if fewer than 3 findings meet the quality bar (evidence, impact, effort, confidence), stop and report that honestly rather than padding the list. A short list of high-confidence, high-leverage specs beats a long one.
+
+When running non-interactively (no user available to choose), write specs for the top 3–5 by leverage and record that default in `specs/README.md`.
 
 ## Workflow
 
 ### Phase 1 — Recon (always)
 
 Map the territory before judging it:
 
-- Read `README`, `CLAUDE.md`/`AGENTS.md`, `CONTRIBUTING`, root config files (`pyproject.toml`, `Cargo.toml`, `package.json`, etc.), CI config, and the directory structure.
-- Identify: language(s), framework(s), package manager, **how to build / test / lint / typecheck** (exact commands — these go into every spec as verification gates), test coverage shape, deployment target.
-- Note repo conventions: code style, naming, folder layout, error-handling and state-management patterns. Specs must tell the builder to *match* these, with examples.
-- Check git signal where useful (`git log --oneline -30`, churn hotspots) for what's actively evolving vs. frozen.
-- **Generate `specs/context.md`** — a comprehensive project context document that builders can reference. This is the "shared memory" for all specs generated from this audit.
-
-**Verification commands for this project (uv-managed Python):**
-
-| Purpose   | Command                           | Expected on success |
-|-----------|-----------------------------------|---------------------|
-| Install   | `uv sync --all-groups`            | exit 0              |
-| Lint      | `uv run ruff check`               | exit 0, no errors   |
-| Format    | `uv run ruff format --check`      | exit 0              |
-| Typecheck | `uv run ty check`                 | exit 0, no errors   |
-| Tests     | `uv run pytest`                   | all pass            |
-| BDD       | `uv run behave`                   | all pass            |
-| All       | `uv run ruff check && uv run ty check && uv run pytest && uv run behave` | all pass |
+- Read `README`, `CLAUDE.md`/`AGENTS.md`, `CONTRIBUTING`, root config files, CI config, and directory structure.
+- Identify: language(s), framework(s), package manager, **how to build / test / lint / typecheck** (exact commands), test coverage shape, deployment target.
+- Note repo conventions: code style, naming, folder layout, error-handling and state-management patterns. Specs must tell the builder to *match* these.
+- Check git signal where useful (`git log --oneline -30`, churn hotspots).
+- **Generate `specs/context.md`** — a shared-memory document for all specs generated from this audit.
 
-If the repo has no working verification command (no tests, broken build), record that — "establish a verification baseline" is often finding #1, and it must precede risky specs in the dependency order.
+If the repo has no working verification command, record that — "establish a verification baseline" is often finding #1.
 
 #### Generate `specs/context.md`
 
@@ -443,6 +457,6 @@ Generated by pb-improve on <date>. Execute via `/pb-build <feature-name>`.
 - `reconcile` → process what happened since last session: verify DONE specs, investigate BLOCKED ones, refresh drifted TODOs, retire dead findings. Read specs/README.md and every spec's tasks.md, then per status: DONE → spot-check done criteria still hold; BLOCKED → investigate and rewrite or reject; TODO → run drift check and refresh if needed; IN PROGRESS (stale) → flag to user. Finish with a short report.
 - `--issues` (modifier on any planning invocation) → also publish each written spec as a GitHub issue via `gh`, URL recorded in the spec and index. Only with the explicit flag. Preflight: `gh auth status` succeeds and the repo has a GitHub remote. Per spec: `gh issue create --title "<spec title>" --body-file <design.md>`. Labels: `improve` plus the category.
 
-## Tone of the output
+## Output Tone
 
-You are advising, not selling. State findings plainly with evidence, flag uncertainty honestly, and prefer "not worth doing" verdicts over padding the list. A short list of high-confidence, high-leverage specs beats a long one.
+Advise, don't sell. State findings plainly with evidence, flag uncertainty honestly, and prefer "not worth doing" verdicts over padding the list. A short list of high-confidence, high-leverage specs beats a long one.