os-sdlc: pipeline-stages grilled — agent role-noun naming, /os-sdlc:implement, ADR-0044 minimal-prompt discipline

- pipeline-stages settled: from-scratch orchestrator prompt, no pre-programmer
  review (observed-failure-first), test-linting note
- cc-os-naming: agent-name governance resolved (kebab-case role-nouns)
- OVERVIEW: four-phase frame, walk-once→wire→commissioning-ladder sequencing,
  observed-failure-first philosophy bullet; grill queue advanced
- worktree-parallelism: map-ticket + PR-machinery open questions; #73 walk
  hand-patch note

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SiGCD6Kur98fgPKMsJ14Xk

docs/adr/0044-minimal-prompt-discipline-prompt-wording-is-added-only-in-response-to-observed-failures.md

@@ -0,0 +1,27 @@
+---
+id: "0044"
+date: 2026-07-18
+status: Accepted
+supersedes:
+superseded-by:
+affected-paths: [plugins/*/skills/*/SKILL.md, plugins/*/agents/, plugins/*/hooks/]
+affected-components: [os-sdlc, all cc-os plugins with skills/agents/hooks]
+---
+
+# 0044 — Minimal-prompt discipline: prompt wording is added only in response to observed failures
+
+## Context
+
+cc-os prompts (skill instructions, agent definitions, hook-assembled context) tend to accrete defensive wording over time — sentences added speculatively to head off imagined failure modes. This mirrors the pre-deterministic-gates instinct to have an agent's prompt do work that should instead be mechanically enforced. Unchecked, prompt bloat raises token cost, dilutes the sentences that matter, and makes it hard to tell which instructions are load-bearing versus vestigial. The os-sdlc pipeline-stages design (2026-07-18 grill) needed a governing rule for how the from-scratch orchestrator prompt and the named pipeline agents (test-writer, programmer, reviewer) should be written, and the user stated this as a general preference for all projects, not just cc-os.
+
+## Decision
+
+Every prompt in cc-os — skill SKILL.md body, agent definition, and hook-assembled context packet — starts with the fewest sentences that state the job, the inputs, and the return format. Wording is added ONLY in response to an observed failure: an audit finding, an eval miss, or a broken run. Each addition must be traceable to the specific failure that justified it (e.g. a code comment, commit message, or doc note naming the failure). Any sentence in a prompt that cannot be traced to an observed failure is a deletion candidate. This is the prompt-level twin of the deterministic-gates philosophy (ADR governing mechanical enforcement over prose instruction): where gates push correctness out of prompts into hooks, minimal-prompt discipline keeps what remains in prompts lean and evidence-backed.
+
+## Consequences
+
+Easier: prompts stay auditable — every sentence has a paper trail, so reviewing a prompt for bloat is a matter of checking traceability rather than re-deriving whether each sentence is still needed. Token cost per prompt stays low by construction. Harder: authors must resist the urge to preempt failure modes they can imagine but haven't observed; this requires discipline especially when a plausible-sounding safeguard has no incident behind it yet, and it means some real failures will happen once before their guard is written (accepted tradeoff — the alternative is unbounded preemptive bloat). Requires a lightweight convention (comment or note) for tracing each addition to its triggering failure, or the discipline degrades into an unenforced norm.
+
+## Alternatives rejected
+
+Preemptive completeness (write every safeguard a designer can imagine up front) — rejected: this is exactly the failure mode that produced bloated, hard-to-audit prompts in prior art (DeltaRefinery and general experience with the mattpocock skills), and it front-loads cost for failures that may never occur. Periodic prompt review/pruning on a schedule instead of failure-triggered — rejected: schedule-based review still requires someone to guess which sentences are load-bearing without a traceability record, and doesn't prevent bloat from accumulating between reviews. No governing rule, leave it to author judgment per prompt — rejected: judgment alone is what produced the current inconsistency across cc-os prompts; a stated, citable rule is needed so any prompt-editing session (human or AI) has a shared bar.

docs/adr/README.md

@@ -50,4 +50,5 @@ One file per decision, `NNNN-kebab-title.md`, created via `/os-adr:create`.
 | 0041 | [Determinism promotion: hygiene nudges projects toward structurally-obvious completion conventions](0041-determinism-promotion-hygiene-nudges-projects-toward-structurally-obvious-completion-conventions.md) | Accepted | 2026-07-14 |
 | 0042 | [Retire Planka: git issues are the single tracker for state and specs](0042-retire-planka-git-issues-are-the-single-tracker-for-state-and-specs.md) | Accepted | 2026-07-16 |
 | 0043 | [Absolute delegation policy: main loop as executive with enumerated exemptions](0043-absolute-delegation-policy-main-loop-as-executive-with-enumerated-exemptions.md) | Accepted | 2026-07-17 |
+| 0044 | [Minimal-prompt discipline: prompt wording is added only in response to observed failures](0044-minimal-prompt-discipline-prompt-wording-is-added-only-in-response-to-observed-failures.md) | Accepted | 2026-07-18 |
 <!-- adr-index:end -->

plugins/cc-architect/references/conventions/cc-os-naming.md

@@ -26,6 +26,16 @@ An explicit `name: find` collapses the command to bare unnamespaced `/find`
 After any SKILL.md edit, run `bin/refresh-plugins` — installs copy files into
 `~/.claude/plugins/cache/`, so source edits don't reach sessions until refreshed.
 
+## Agents
+
+Decided 2026-07-18, first applied in os-sdlc (`test-writer`, `programmer`, `reviewer`).
+
+- **Agents are kebab-case role-nouns naming the actor** — who does the job, not what action
+  it takes: `test-writer`, `programmer`, `reviewer`. Verb-first is a **skills-only** rule
+  (skills = actions; agents = actors) and does not apply to agent names.
+- **Agents are not user-invocable** — they get no slash commands and no `/plugin:agent`
+  namespaced form. They are dispatched by skills/orchestrators, never typed by a human.
+
 ## Anti-patterns
 
 - Plugin name without the `os-` prefix (`vault` instead of `os-vault`).
@@ -36,9 +46,9 @@ After any SKILL.md edit, run `bin/refresh-plugins` — installs copy files into
 
 ## Open questions
 
-Agent-name and hook-script-name governance are deferred until their use patterns
-stabilize; hook scripts currently use snake_case (Python convention) and are not
-externally visible.
+Hook-script-name governance is deferred until its use patterns stabilize; hook scripts
+currently use snake_case (Python convention) and are not externally visible. (Agent-name
+governance is resolved above, 2026-07-18.)
 
 ## Cross-references
 

plugins/os-sdlc/OVERVIEW.md

@@ -1,6 +1,6 @@
 # os-sdlc — overview & concept map (v0.2)
 
-_Last updated: 2026-07-17. Status: design mapped, no implementation yet._
+_Last updated: 2026-07-18. Status: design mapped, no implementation yet._
 _This is the single entry point: an AI pointed here loads only the reference/
 nodes its task needs, following the map below._
 
@@ -58,7 +58,7 @@ graph TD
 | Node | Status | One-liner |
 |---|---|---|
 | [spec-and-ticket-layer](reference/spec-and-ticket-layer.md) | settled (grilled 2026-07-17) | Git issues are the durable spec layer; wayfinder subsumes levels; adapt wayfinder/to-spec/to-tickets, reuse global grilling; spec + ticket templates fixed |
-| [pipeline-stages](reference/pipeline-stages.md) | direction | The v1 tracer bullet: `/implement` → test-writer → red-assert → programmer → green-assert → reviewer → human merge |
+| [pipeline-stages](reference/pipeline-stages.md) | settled (grilled 2026-07-18) | The v1 tracer bullet: `/os-sdlc:implement` → test-writer → red-assert → programmer → green-assert → reviewer → human merge; agent naming, from-scratch orchestrator prompt, and pre-programmer-review all resolved |
 | [deterministic-gates](reference/deterministic-gates.md) | settled | Hooks, not agents, run tests/lint; red/green asserted mechanically; green command pluggable per project |
 | [agent-design-principles](reference/agent-design-principles.md) | settled | Single job, minimal tool allowlist (programmer: no Bash), settled facts in via prompt, minimum out via return format |
 | [worktree-parallelism](reference/worktree-parallelism.md) | direction | Worktree-per-spec, sequential tickets within a spec, parallel across specs, human merge gate |
@@ -82,13 +82,44 @@ graph TD
   **engineer** (fixed start/end gates), or **agent** (judgment) — never default
   to agent.
 - **Composability with os-* siblings is a hard constraint** (ADR-023).
+- **Observed-failure-first** — no standing stage, agent split, or prompt instruction is added
+  preemptively; each exists only in response to an observed failure (an audit finding, an
+  eval miss, a broken run), and audits are the trigger to revisit. This rule already decided
+  [pipeline-stages](reference/pipeline-stages.md)'s no-programmer-split, no-refactor-stage,
+  and no-pre-programmer-review calls; at the prompt-wording level it's the same rule as
+  ADR-0044 (minimal-prompt discipline).
+
+## Four phases
+
+| Phase | Who/what | Mechanism |
+|---|---|---|
+| Ideation | User + AI | grill → to-spec |
+| Decomposition | to-tickets skill, acting as the PM | sizing rule: 3–7 Given/When/Then criteria enforced in the ticket template |
+| Implementation | `/os-sdlc:implement` pipeline | test-writer → gates → programmer → reviewer |
+| Acceptance | Human merge gate | orchestrator presents, human merges; worktree per spec deleted after merge |
 
 ## Build sequencing
 
-v1 = the tracer bullet in [pipeline-stages](reference/pipeline-stages.md),
-triggered manually, walked by hand once with disposable code and trivial prompts
-before wiring into skills/hooks/agents. **Code quality is deliberately a later
-phase:** [standards-and-conventions](reference/standards-and-conventions.md) and
+v1 = the tracer bullet in [pipeline-stages](reference/pipeline-stages.md). Sequence, in
+order:
+
+1. **Walk once** — the tracer bullet is performed by hand, once, in a real git worktree,
+   with disposable code and trivial prompts, `.cc-os/config` manually copied in to work
+   around [worktree-parallelism](reference/worktree-parallelism.md)'s Forgejo issue #73. This flushes
+   out the real choreography before anything is wired.
+2. **Wire** — the proven choreography is built into skills/hooks/agents. The native fix for
+   issue #73 (walk-up to repo root vs. provision-at-creation — the choice is informed by what
+   the walk showed) is a hard dependency of this step.
+3. **Commissioning ladder** — once wired, a named build phase runs the pipeline through
+   progressively harder challenges (complexity more than size), each deliberately designed to
+   trip the AI up. Every run is tri-audited — Fable, Codex, and the human — with fixes applied
+   lint-first, prompt-second (per ADR-0044's minimal-prompt discipline). Lint/prompt changes
+   merge to main; app worktrees used for the challenges are disposable. The same problem
+   repeats until the pipeline nails it without help, then the ladder climbs a rung; it
+   continues until confidence is ~99% or returns diminish.
+
+**Code quality is deliberately a later phase:**
+[standards-and-conventions](reference/standards-and-conventions.md) and
 [debugger](reference/debugger.md) are post-tracer-bullet, built alongside
 [self-improvement-loops](reference/self-improvement-loops.md) — nail the flow
 first, dial in quality once the happy path is trusted. Everything in
@@ -98,8 +129,8 @@ carries none.
 
 **Grill queue** (decided 2026-07-16): the critical path is
 [spec-and-ticket-layer](reference/spec-and-ticket-layer.md) (✅ grilled 2026-07-17) →
-[pipeline-stages](reference/pipeline-stages.md) — next up.
-Then [never-ask-twice](reference/never-ask-twice.md) +
+[pipeline-stages](reference/pipeline-stages.md) (✅ grilled 2026-07-18) — next up:
+[never-ask-twice](reference/never-ask-twice.md) +
 [self-improvement-loops](reference/self-improvement-loops.md) (can run in
 parallel with pipeline build; NAT's formalization ADR is independent), then
 [horizon](reference/horizon.md). The remaining nodes' open questions are

plugins/os-sdlc/reference/pipeline-stages.md

@@ -1,18 +1,27 @@
 # pipeline stages
 
-_Status: direction — as of 2026-07-16_
+_Status: settled — grilled 2026-07-18_
 _Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [pipeline-observability](pipeline-observability.md), [standards-and-conventions](standards-and-conventions.md), [debugger](debugger.md), [overview](../OVERVIEW.md)_
 
 ## Purpose
 
-Defines the v1 tracer-bullet pipeline shape for `/implement <ticket>`: the ordered stages,
-which actor (code/engineer/agent) owns each, and the two decisions that keep the pipeline at
-one-agent-one-job grain. Load this before designing any pipeline stage, skill, or agent
-definition for os-sdlc.
+Defines the v1 tracer-bullet pipeline shape for `/os-sdlc:implement <ticket>`: the ordered
+stages, which actor (code/engineer/agent) owns each, and the three decisions that keep the
+pipeline at one-agent-one-job grain. Load this before designing any pipeline stage, skill, or
+agent definition for os-sdlc.
 
 ## Design
 
-Manually triggered by `/implement <ticket>`. Stages, in order:
+Manually triggered by `/os-sdlc:implement <ticket>` — an orchestrator skill consuming exactly
+one ticket as argument. The orchestrator prompt is written from scratch: none of Matt
+Pocock's `implement` wording survives, since his prompt assumes a single agent running its
+own tests, which contradicts [deterministic-gates](deterministic-gates.md) (hooks, not
+agents, run tests). Pocock's `implement` stays in Sources as lineage only. Like every prompt
+in this pipeline, the orchestrator prompt follows the minimal-prompt discipline
+(ADR-0044): start from the fewest sentences stating the job, inputs, and return format, and
+add wording only in response to an observed failure.
+
+Stages, in order:
 
 1. **Ticket intake** (code) — reads the issue via the `os-backlog` tracker key
    (`.cc-os/config`); no new ticketing system, per ADR-0037's composability constraint.
@@ -29,7 +38,11 @@ Manually triggered by `/implement <ticket>`. Stages, in order:
    reviewer below.
 6. **Reviewer agent** — a *named agent* (not a skill), so its tool surface is minimal and
    its context never leaks into the orchestrator's (see
-   [agent-design-principles](agent-design-principles.md)). It reads only a hook-assembled
+   [agent-design-principles](agent-design-principles.md)). Named `reviewer`, alongside
+   `test-writer` and `programmer` — cc-os's first named agents. Agent names are kebab-case
+   role-nouns naming the actor (who does the job), distinct from the verb-first rule that
+   governs skill names (see
+   `plugins/cc-architect/references/conventions/cc-os-naming.md`). It reads only a hook-assembled
    context packet — test status from the green-assert gate (passing, unless max-iterations
    escalated), a mechanically generated diff, and the spec/ticket — gathered into one
    document by a code-actor hook before the agent is invoked; the reviewer runs nothing
@@ -50,7 +63,7 @@ Manually triggered by `/implement <ticket>`. Stages, in order:
 8. **Human merge gate** — v1 has no automated merge; see
    [worktree-parallelism](worktree-parallelism.md).
 
-Two decisions fix the grain of this pipeline:
+Three decisions fix the grain of this pipeline:
 
 - **One programmer agent, not seam-creator/implementor.** The seam is not a judgment
   boundary — splitting it adds a handoff and context loss for no trust gain. This is exactly
@@ -60,29 +73,37 @@ Two decisions fix the grain of this pipeline:
 - **Refactor is not a standing stage.** The reviewer's critique triggers a correction loop —
   re-invoking the programmer with findings — using the same feedback mechanism as a failing
   gate, rather than a dedicated pipeline stage.
+- **No pre-programmer tests-vs-spec review stage.** The reviewer's first ordered check (stage
+  6, above) already covers tests-vs-spec alignment; adding a second, earlier review of the
+  same question buys nothing but a cheaper failure mode — the only cost of catching a
+  misaligned test late is one wasted programmer run. Revisit only if audits show a pattern of
+  wasted programmer runs traced to misaligned tests. Related: mechanically lintable TEST
+  standards (linting tests like code, per
+  [standards-and-conventions](standards-and-conventions.md)) further shrink what's left for
+  the reviewer to catch by judgment at all.
 
 Grain: one ticket, one vertical slice. TDD is internal to the stage (test-writer then
 programmer within one ticket's run), never orchestrated per-example from outside — that
 per-example granularity was a DeltaRefinery downside being deliberately dropped.
 
-## Open questions
+## Resolved 2026-07-18
 
-- Skill/agent naming for each stage (test-writer, programmer, reviewer) — must follow the
-  cc-os naming convention before anything ships.
-- Whether a cheap tests-vs-spec review should run *before* the programmer stage in later
-  versions, to catch misaligned tests before paying for implementation.
-- Shape settled 2026-07-16: `/implement` (or our custom successor) is a *skill acting as
-  orchestrator* — slash commands are the user-invocable layer, agents aren't. The skill
-  triggers the agent pipeline, watches over it, adjusts to surprises, and keeps the user
-  in the loop on progress/results. Remaining question: how much of Pocock's `implement`
-  wording survives vs. a from-scratch orchestrator prompt.
+Agent naming, orchestrator-prompt provenance, and the pre-programmer-review question (all
+open as of 2026-07-16) are settled above. No open questions remain in this doc; the tracer
+walk (rung zero of build sequencing, see [overview](../OVERVIEW.md)) is performed by hand,
+once, in a real git worktree with `.cc-os/config` manually copied in to work around
+[worktree-parallelism](worktree-parallelism.md)'s Forgejo issue #73 — the native fix for #73
+is a hard dependency of wiring this pipeline into skills/hooks/agents.
 
 ## Sources
 
 - ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
 - ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
+- ADR-0044 (2026-07-18, minimal-prompt discipline)
+- `plugins/cc-architect/references/conventions/cc-os-naming.md` (agent naming, added
+  2026-07-18)
 - `plugins/os-sdlc/OVERVIEW.md`
 - SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md`,
   `matt-pocock-skills-v1-1-changes.md`
 - `~/dev/delta-refinery` (prior art, principles kept/dropped as noted above)
-- 2026-07-16 design session (this doc's origin)
+- 2026-07-16 design session (this doc's origin); grilled 2026-07-18

plugins/os-sdlc/reference/worktree-parallelism.md

@@ -27,17 +27,28 @@ multi-ticket/multi-spec orchestration for os-sdlc.
   inherit the tracker key, and `os-backlog` issue-create fails inside them. This blocks
   ticket-intake (stage 1 of [pipeline-stages](pipeline-stages.md)) from working inside a
   worktree today. The factory needs a native fix — either walking up to the owning repo root
-  to find the config, or provisioning `.cc-os/config` at worktree-creation time.
+  to find the config, or provisioning `.cc-os/config` at worktree-creation time. Per
+  [pipeline-stages](pipeline-stages.md)'s build sequencing: the once-only tracer walk
+  hand-patches around this bug by manually copying `.cc-os/config` into the walk's worktree;
+  the native fix (chosen from what the walk shows) is a hard dependency of the wiring step
+  that follows the walk, so it must land before wiring starts.
 
 ## Open questions
 
 - Whether Pocock's `wayfinder:map` tags should drive merge choreography — check the vault
   note `matt-pocock-skills-v1-1-changes.md` when designing this; not yet evaluated against
-  os-sdlc's spec/ticket model.
+  os-sdlc's spec/ticket model. Related, sharper version of the same question: whether each
+  spec should get an orchestration/"map" ticket that tracks its constituent tickets and their
+  pipeline state, owned by the orchestrator, and used to drive merge choreography across a
+  spec's worktree.
 - Worktree lifecycle automation: who creates a worktree for a new spec, who cleans it up after
   merge, and what triggers each.
 - Branch naming convention for spec-level and (if they ever become worth it) per-ticket
   branches under a spec branch.
+- **PR-machinery plan.** [pipeline-stages](pipeline-stages.md) stage 8 is a human merge gate
+  in v1. Before that gate can automate, a plan is needed for what replaces it: PR creation,
+  review attachment, and merge policy. Not scoped yet — flagged here so automation of the
+  merge gate doesn't get built without one.
 
 ## Sources